AHMED ZBYR

AHMED ZBYR

Biker, EV Enthusiast

Pandoc is an open-source universal document converter capable of transforming technical documentation written in Markdown into PDF, Microsoft Word (.docx), HTML, LaTeX, EPUB, man pages, and dozens of other formats—or converting existing HTML pages and Word documents back into clean Markdown.

Supported Formats Overview

As described on pandoc.org, Pandoc can convert documents between:

  • Lightweight markup formats: Markdown (including GitHub Flavored Markdown and CommonMark), reStructuredText, AsciiDoc, MediaWiki, DokuWiki, Emacs Org-Mode, and Textile.
  • HTML formats: XHTML, HTML5, and HTML slide decks (Reveal.js, Slidy, Slideous, S5, DZSlides).
  • Word processor formats: Microsoft Word (.docx), LibreOffice/OpenOffice ODT, and OpenDocument XML.
  • Typesetting & PDF formats: LaTeX, ConTeXt, LaTeX Beamer slides, and PDF (via pdflatex, xelatex, lualatex, wkhtmltopdf, or weasyprint).
  • Documentation & Ebook formats: EPUB v2/v3, DocBook, GNU TexInfo, Groff man pages, and Haddock markup.

Pandoc also supports YAML metadata blocks (title, author, date, geometry), footnotes, tables, syntax-highlighted code blocks, citations, and inline LaTeX math.

Step 1: Install Pandoc and TeX Live

Generating PDFs via LaTeX requires both pandoc and a TeX engine (such as texlive / texlive-xetex).

CentOS / RHEL / Fedora

(On CentOS/RHEL, enable EPEL first if pandoc is not in the base repository: sudo yum install epel-release.)

sudo yum install -y pandoc texlive texlive-xetex

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y pandoc texlive texlive-xetex

Step 2: Convert Markdown Files to PDF

1. Create a Sample Markdown File

Create a working directory with a sample Markdown tutorial (markdown/2016-08-15-firstmarkdownfile.md):

mkdir -p ~/markdown ~/pdf

Example contents of ~/markdown/2016-08-15-firstmarkdownfile.md:

# How To Configure Swappiness

Swappiness is a Linux kernel parameter that controls the relative weight given to swapping out runtime memory, as opposed to dropping pages from the system page cache. Swappiness can be set to values between 0 and 100 inclusive.

| Value | Strategy |
| :--- | :--- |
| `vm.swappiness = 0` | The kernel will swap only to avoid an out-of-memory condition. |
| `vm.swappiness = 1` | Kernel 3.5+ and 2.6.32-303+: minimum swapping without disabling it entirely. |
| `vm.swappiness = 10` | Recommended to improve performance when sufficient RAM exists. |
| `vm.swappiness = 60` | Default Linux kernel setting. |
| `vm.swappiness = 100` | The kernel will swap aggressively. |

To temporarily set swappiness in Linux:

```sh
# Set swappiness value as root
sysctl -w vm.swappiness=10

# Verify the current setting
cat /proc/sys/vm/swappiness

To make the change persistent across reboots, add vm.swappiness=10 to /etc/sysctl.conf.


### 2. Batch-Convert Markdown Files to PDF with a Shell Script

Create `~/pdf/create_pdf_from_md.sh` to iterate over Markdown files in `../markdown/` and render each one to PDF with custom 2 cm horizontal margins and 1 cm vertical margins:

```sh
#!/usr/bin/env bash
set -euo pipefail

shopt -s nullglob
for input_file in ../markdown/201*.md; do
    base_name="$(basename "$input_file" .md)"
    output_file="${base_name}.pdf"

    if [ -f "$output_file" ]; then
        echo "File '$output_file' is already converted to PDF."
    else
        echo "Converting '$input_file' -> '$output_file'..."
        pandoc -f markdown \
               -o "$output_file" \
               -V geometry:"left=2.0cm, right=2.0cm, top=1.0cm, bottom=1.0cm" \
               --pdf-engine=xelatex \
               "$input_file"
    fi
done

Note on Pandoc CLI Flags:

  • In Pandoc 2.0 and newer, --latex-engine=xelatex was renamed to --pdf-engine=xelatex. (If you are running an older Pandoc 1.x package on CentOS 6/7, use --latex-engine=xelatex.)
  • When -o filename.pdf is specified, Pandoc automatically selects PDF output via LaTeX, so you do not need to pass duplicate -t pdf -w pdf -t latex flags.

Run the script from ~/pdf:

cd ~/pdf
chmod +x create_pdf_from_md.sh
./create_pdf_from_md.sh

Here is the resulting rendered PDF:

pdf generate demo

Step 3: Convert a Web Page (HTML) to Word (.docx)

Pandoc can also fetch a live URL (or read a local .html file) and convert it directly into a Microsoft Word .docx document:

pandoc -f html -t docx -o chef-server-setup.docx https://ahmedzbyr.gitlab.io/chef-server-setup/

Other Useful One-Liners

  • Markdown to standalone HTML5 with a Table of Contents: 
    pandoc -s --toc -f markdown -t html5 input.md -o output.html
  • Word (.docx) to GitHub Flavored Markdown (extracting embedded images to ./media): 
    pandoc --extract-media=./media -f docx -t gfm document.docx -o document.md

References

You May Also Enjoy