How to Convert Markdown Documents to PDF and HTML in Linux Terminal Using Pandoc

Markdown is the universal standard for technical documentation, developer notes, README files, and static website content due to its clean syntax and human-readable plain text structure. However, sharing documents with external clients, academic institutions, or executive teams often demands formally formatted PDF reports or standalone styled HTML pages.

Pandoc is known as the “Swiss Army knife” of document conversion, capable of transforming Markdown into dozens of rich document formats from the Linux command line. By combining Pandoc with lightweight PDF rendering engines (such as wkhtmltopdf or pdflatex) and standalone HTML templates, you can automate documentation pipelines and generate publication-quality outputs in seconds.

Installing Pandoc and Rendering Engines on Ubuntu and Debian

Pandoc requires an external typesetting or rendering engine to compile PDF documents from intermediate Markdown.

1. Launch your terminal and update your local package list:

   sudo apt update

2. Install Pandoc:

   sudo apt install pandoc -y

3. Choose and install a PDF rendering engine:
   • Option A (Lightweight, web-friendly): Install wkhtmltopdf or weasyprint for fast CSS-based rendering:

     sudo apt install wkhtmltopdf -y

   • Option B (Academic & scientific): Install a minimal LaTeX distribution for mathematical formulas and formal book layouts:

     sudo apt install texlive-latex-base texlive-fonts-recommended texlive-extra-utils -y

4. Confirm your Pandoc installation and supported format engines:

   pandoc --version

Converting Markdown to Styled Standalone HTML

By default, Pandoc outputs an HTML fragment containing only body tags. To generate a complete, valid HTML document with embedded CSS styling:

1. Navigate to your document directory:

   cd ~/Documents/reports/

2. Run Pandoc using the standalone (-s) flag and title metadata:

   pandoc input.md -s -o output.html --metadata title="Project Documentation"

3. To embed custom modern CSS typography and responsive styling directly into the generated file:

   pandoc input.md -s --css style.css --self-contained -o index.html

   The --self-contained (or --embed-resources) option bundles images and CSS styles directly into the output file, making it completely portable.

Converting Markdown to PDF with Custom Margins and Typography

Compile a clean PDF report specifying margins, engine drivers, and table of contents:

1. To convert Markdown directly to PDF using the wkhtmltopdf engine:

   pandoc input.md -o report.pdf --pdf-engine=wkhtmltopdf -V margin-top=20mm -V margin-bottom=20mm -V margin-left=25mm -V margin-right=25mm

2. To generate an academic PDF with a table of contents and numbered sections via LaTeX:

   pandoc input.md -o whitepaper.pdf --toc --number-sections -V geometry:margin=1in -V fontsize=11pt

   • --toc: Automatically parses H1, H2, and H3 headers to construct an interactive Table of Contents.
   • --number-sections: Automatically numbers document chapters (e.g., 1.0, 1.1, 2.0).
   • -V geometry:margin=1in: Sets standard 1-inch printable margins throughout.

Batch Converting Multiple Markdown Files in a Directory

Automate document generation across entire repositories using a concise Bash loop:

for f in *.md; do
  [ -f "$f" ] || continue
  pandoc "$f" -o "${f%.md}.pdf" --pdf-engine=wkhtmltopdf -s
  echo "Converted $f to ${f%.md}.pdf"
done

Troubleshooting Common Pandoc Compilation Errors

• Missing PDF engine error: If Pandoc reports “pdflatex not found”, specify an installed engine explicitly using --pdf-engine=wkhtmltopdf or --pdf-engine=xelatex.
• Broken image paths: Ensure all relative image links referenced inside your Markdown file (e.g., ![Diagram](images/diag.png)) exist relative to the working directory where Pandoc is executed.
• Unicode and special character errors: When rendering non-ASCII or international fonts with LaTeX, use the XeLaTeX engine: --pdf-engine=xelatex -V mainfont="DejaVu Sans".