Markdown to PDF — convert MD files with syntax highlighting

Markdown flavours, in plain English

There is no single Markdown spec — there are several, and which one your converter speaks affects what survives. The four most-common variants in 2026:

CommonMark is the most-portable baseline — every Markdown converter speaks it.¹ GitHub Flavored Markdown adds the bits most users actually want (tables, task lists) and is supported by every converter in the table below.² Pandoc Markdown is the most expressive and is the only variant that survives all of Pandoc's features.³

Five tools compared

Syntax highlighting that actually works

The single most-asked-for feature in Markdown-to-PDF tooling is good code-block highlighting. Three things have to line up for it to work:

1. Fenced code blocks with a language hint. Use three backticks and the language identifier on the opening fence. Without a language, the highlighter has nothing to colour against.
2. A highlighter that supports the language. highlight.js (used by ScoutMyTool and VS Code) supports nearly 200 languages out of the box. Pandoc uses the Kate-highlight engine with similarly broad coverage. Both engines fall back to plain monospace for unknown languages rather than crashing.
3. A theme that prints legibly. Dark themes look great on screen but waste toner and reduce contrast in printed PDF. The "GitHub" or "atom-one-light" themes are the safest choice for printable output; switch to dark themes only for screen-only PDFs.

For programming-heavy documents (technical specs, runbooks, code-review notes), ScoutMyTool's Code to PDF tool can produce a syntax-highlighted PDF directly from a source file — no Markdown wrapping needed. Use it when the document is mostly code with light annotation.

Math, diagrams, and front matter

Three more features that matter for the kinds of documents people write in Markdown:

• LaTeX math. Surround inline math with single dollar signs ($E = mc^2$) and display math with double dollar signs. KaTeX renders most undergraduate math correctly and is fast enough for browser-based pipelines. Pandoc supports MathJax (slower but more complete) and MathML (best for accessibility tools that speak math).
• Mermaid diagrams. Fenced blocks with the language hint mermaid are interpreted as flowcharts, sequence diagrams, ER diagrams, or Gantt charts and rendered as embedded SVG in the PDF. The native support in ScoutMyTool and VS Code Markdown PDF makes Mermaid the simplest way to embed a flowchart in a Markdown source.
• YAML front matter. A block of YAML at the very top of the file (delimited by --- on both sides) carries metadata. Most modern tools read fields like title, author, date, and toc, and use them for the PDF metadata, cover page, or running header. The same convention is used by Jekyll, Hugo, Astro, and most static site generators.

Converting via ScoutMyTool — five steps

1. Open the tool. Go to scoutmytool.com/pdf/markdown-to-pdf. The page loads as static HTML; the conversion runs entirely in your browser tab.
2. Drop in the .md file or paste the Markdown. The tool parses with markdown-it (which speaks CommonMark and GFM by default).
3. Pick a theme. Default (GitHub-style), Academic (Times-style with numbered headings), Minimal (single-column body, narrow margins). Custom CSS upload is available for branded output.
4. Enable optional features. Math (KaTeX), Mermaid diagrams, syntax-highlighted code (highlight.js with theme picker), front-matter cover page, and page numbering.
5. Convert. The tool renders to HTML, applies the chosen CSS, then uses pdf-lib to compose the paginated PDF. The result downloads to your machine. No network round-trip means even multi-megabyte Markdown files convert in seconds.

When to use Pandoc instead

Pandoc is the heavyweight of Markdown-to-PDF conversion and the right pick for three specific scenarios:

• Academic papers with citations. Pandoc accepts a .bib file via --bibliography and renders citations + bibliography in the chosen style (APA, MLA, Chicago, etc.). No browser-based tool comes close.
• Complex multi-format pipelines. Pandoc converts between Markdown, LaTeX, HTML, EPUB, DOCX, and more in any combination. If you produce the same document in multiple formats (e.g., LaTeX paper + EPUB book + PDF preprint), Pandoc is the single tool to learn.
• Custom templates with full LaTeX control. Pandoc's template system gives you complete control over the PDF output — page geometry, headers, footers, custom commands. The learning curve is steeper than a CSS theme but the ceiling is higher.

For everything else — README files, design docs, runbooks, blog drafts, meeting minutes — a browser-based or VS Code extension is faster to set up, faster to run, and produces equally good output.

Related ScoutMyTool tools and articles

• Markdown to PDF — the primary tool referenced.
• PDF to Markdown — the reverse direction.
• Code to PDF — for pure source files with syntax highlighting.
• HTML to PDF — for HTML output that you may have generated from Markdown.
• Text to PDF — for plain unstyled text.
• Compress PDF — shrink the resulting PDF before sharing.
• HTML to PDF article — sister piece on the web-page side.
• Word to PDF article — sister piece on Word documents.

Frequently asked questions

Which Markdown flavour should I write in for PDF output?

GitHub Flavored Markdown (GFM) is the right default for most users — it is the variant GitHub README files use, has wide tool support, and adds pipe tables and task lists to CommonMark. For academic writing with footnotes, citations, and complex tables, Pandoc Markdown is more expressive. For documents where you need to share the .md source with non-technical readers, stick to plain CommonMark — its restrictions make it the most-portable variant. The good news: every PDF converter discussed in this article supports CommonMark and GFM. Pandoc Markdown is supported only by Pandoc itself.

Will fenced code blocks have syntax highlighting in the PDF?

Yes, if your converter supports it and you specify the language. Use the three-backtick fence with a language hint: ```python (or javascript, typescript, rust, go, bash, sql, css, html). The highlighter recognises the language and colours keywords, strings, numbers, and comments according to the chosen theme. ScoutMyTool uses highlight.js with the GitHub theme by default; pandoc uses the Kate-highlight engine; VS Code's Markdown PDF extension uses highlight.js with the editor's current theme. For Markdown without language hints, code blocks render as monospace without colour.

How do I include LaTeX math equations?

Use $ inline$ or $$display$$ delimiters with LaTeX expressions. For example, $E = mc^2$ inline, or $$\\int_0^1 x^2 \\, dx = \\tfrac{1}{3}$$ for a display equation. ScoutMyTool renders these with KaTeX, which supports a sizeable subset of LaTeX. Pandoc has multiple math engines (MathML, MathJax, KaTeX) selectable via --mathml/--mathjax/--katex. The output PDF embeds the equations as vector graphics, so they remain crisp at any zoom level. Limitations: not every LaTeX package is supported (no TikZ in KaTeX, for example) — for very advanced math, use Pandoc with the appropriate engine.

Can I render Mermaid diagrams?

Yes, with the right tool. ScoutMyTool's Markdown converter recognises ```mermaid fenced blocks and renders them as embedded SVG diagrams in the PDF. The same workflow works in VS Code with the Markdown PDF extension. Pandoc requires a filter (mermaid-filter or equivalent). Plain wkhtmltopdf and basic pandoc do not handle Mermaid out of the box. For a presentation-quality flowchart in your README, fenced ```mermaid blocks are usually the simplest path.

Are my Markdown files uploaded anywhere when I use a free converter?

Only if the converter is server-based. ScoutMyTool's Markdown-to-PDF tool runs entirely in your browser tab — your .md file is parsed locally with markdown-it, the resulting HTML is laid out with pdf-lib + a built-in CSS engine, and the PDF is downloaded directly. Nothing leaves your machine. Some server-side "MD to PDF" services upload your file, render it on their infrastructure, and stream back the result; for confidential design docs, RFC drafts, internal product specs, the client-side path is the only one that keeps the source off third-party servers.

How do I add a custom theme or stylesheet?

Most browser-based and editor-based tools let you supply a CSS file that styles the rendered HTML before the PDF pass. ScoutMyTool exposes a theme picker (default, GitHub-style, academic, minimal) and accepts a custom CSS upload that overrides the defaults. Pandoc accepts --css for HTML-then-PDF pipelines and a wide range of templates via --template. For corporate documents that need brand fonts, colours, headers and footers, building a small custom CSS once and applying it on every conversion is usually faster than configuring a full template.

What about front matter (YAML at the top of the .md file)?

Front matter is a YAML block at the start of a Markdown file (delimited by --- on both sides) that carries metadata like title, author, date, and tags. Most modern Markdown-to-PDF tools recognise it and use it for the PDF metadata (title, author shown in the viewer) and optionally for a cover page or running header. ScoutMyTool reads front-matter title/author/date and renders them as a title block at the top of the first page; pandoc consumes the same fields and supports custom templating via Pandoc variables.