Markdown to PDF with Pandoc and Typst

Pandoc is a document converter, not just a Markdown printer. It parses Markdown into a structured document with headings, paragraphs, lists, code blocks, tables, citations, and metadata. Then it writes another format, optionally using a PDF engine.

Markdown flavor matters. Pandoc Markdown supports extensions that CommonMark or GitHub Flavored Markdown may not. If a README uses task lists, pipe tables, raw HTML, or footnotes, confirm which extensions are enabled before blaming the PDF engine.

Typst is a typesetting system that can produce PDFs without a LaTeX installation. With Pandoc 3.6.4, pandoc in.md -o out.pdf --pdf-engine=typst is a practical route for many reports, specs, and notes.

Typst is not a drop-in clone of LaTeX. Some LaTeX-specific Pandoc templates, packages, or raw TeX snippets will not work. If your source depends on LaTeX packages, use a LaTeX engine instead or remove those dependencies.

Start with pandoc in.md -o out.pdf --pdf-engine=typst. Add metadata with -M title="Quarterly notes" -M author="Team". Add a table of contents with --toc when headings are well structured.

For HTML-heavy Markdown, consider converting to HTML first with pandoc in.md -o out.html and reviewing the structure. Raw HTML may pass through differently depending on the writer and extensions.

Markdown tables are limited. Wide tables may overflow a PDF page unless you change page size, reduce columns, or use a different output layout. Code blocks need language tags if you expect highlighting, and long lines may need wrapping.

Images should use stable relative paths from the Markdown file. A conversion run from the wrong working directory often fails because [chart image](images/chart.png) no longer points to an existing file. Keep assets beside the document or pass resource paths deliberately.

If the PDF build fails, reduce the Markdown to the smallest failing section. Check YAML front matter indentation, fenced code blocks that are not closed, and tables with inconsistent pipe counts. A syntax issue in source often appears as a PDF-engine error.

For repeatable output, commit the command, Pandoc version, Typst version, and any templates. Small version changes can alter line breaks, default fonts, or table rendering.

Version pinning matters for generated PDFs. Record pandoc --version and typst --version in the build logs, especially when PDFs are committed as release artifacts. A changed default font, heading spacing, or table rule can create noisy diffs even if the Markdown did not change.

For collaborative writing, keep source Markdown simple. Deeply nested raw blocks, local filters, and one-off template hacks make the PDF path fragile for the next editor. Use metadata and a small reference template before reaching for custom code.

Automated builds should fail loudly when assets are missing. A PDF with a skipped image may still be produced in some workflows, but the document is incomplete. Treat missing resources as build errors for release notes, manuals, and client documents.

Keep examples close to the source. If a document includes code snippets, generate the PDF from the same repository revision as the code being described.

A final PDF job should run in a clean working directory or container. Hidden local fonts, missing environment variables, and stale generated images are common reasons a document builds on one laptop but not in CI.

For tables, include one deliberately wide example in tests. It shows whether the chosen page size and styling can handle real content.