Note on Pandoc Usage - Convert Markdown to TeX/PDF

Introduction

Pandoc is a versatile tool that simplifies the conversion of markdown files to different formats such as LaTeX, PDF, DOCX, and HTML. By utilizing Pandoc, we can conveniently write our documents in markdown and effortlessly convert them to the desired output format. This approach greatly streamlines the writing and organization of documents, making it more convenient than directly writing the manuscript in LaTeX or HTML.

Installation

1. Download TeX Live ISO and install.
2. Install Pandoc.

Usage

Create a markdown file

Before any usage of Pandoc, we need to create a markdown file. An introduction to markdown syntax can be found here. We recommend VS Code with Markdown All in One and Markdown Preview Enhanced extensions as an editor for writing markdown files.

Insert a figure

Pandoc can convert the standard figure insertion instruction ![caption](figure_path) to corresponding LaTeX instruction \begin{figure} ... \end{figure}. The question is how to specify the size and position of this figure. Here are two tips:

• To specify the size of the figure (e.g., setting figure width to 300 px), you can use this markdown instruction ![caption](figure_path){width=300px}.
• To center the figure in markdown, you can invoke HTML instruction as follows:

<center>

![caption](figure_path){width=300px}

</center>

• Note that a blank line should be added between the <center> (</center>) and the figure insertion instruction ![caption](figure_path){width=300px}.

• Please note that if the caption key value is left blank, the figure in LaTeX will not be aligned to the center, instead, it will align to the left.

• All the spaces in the figure_path should be replaced with %20, otherwise the figure won’t display properly.

• If you want to figures to be rendered side-by-side, just put two figure insertion instructions one after another, but separte them with a space, not a line ending, like ![caption1](figure1) ![caption2](figure2).

Set margin size in the pdf

In order to control the margin size of the pdf generated by Pandoc during the convertion of a markdown file, you can add the following header to the markdown file:

---
geometry: margin=1in
---

Custom LaTeX template

If you want to customize the LaTeX template used by Pandoc for generating LaTeX or PDF files, you can cd to the folder where the input markdown is placed, create a new foler pandoc, and create a pandoc_template.latex file here. To activate template during a conversion, please type in the Pandoc conversion command like this:

pandoc input.md -o output.tex --template=./pandoc/pandoc_template.latex

Remember to replace the input.md and ouput.tex with the filename of input and output documents.

Insert full-size horizontal line

If you want to insert a full-size horizontal line in the LaTeX/PDF document generated by Pandoc, in a way like how --- is rendered in markdown, you will need to do take care of the following points:

1. In the input markdown file, make sure there is a blank line between --- and other text.
2. Use a custom LaTeX template for Pandoc, and add a command in the template file to redefine the horizontal line function (rule), otherwise it won’t display as a full-size line.
3. The command of redefinition is:

\let\OldRule\rule
\renewcommand{\rule}[2]{\OldRule{\linewidth}{#2}}

Multiple-line equation

In markdown, multiple-line equations can be created by adding \\ after each line of equation. However, after Pandoc converts a markdown file being converted to a LaTeX file, this break line command will be preserved in the LaTeX file, which won’t render as a break line in the final PDF file.

To fix this issue, a simple way is to redefine the default way that Pandoc renders equations. Specifically, Pandoc uses \[ \] to define equations in LaTeX, but we can add the following command of redefinition in the LaTeX template of Pandoc, which puts every equation in a \begin{align*} \end{align}* environment and thus enables breaking line with \\.

\def\[#1\]{%
  \begin{align*}#1\end{align*}%
}