Markdown to PDF for Developers: Export README, Specs, and Docs with Code and Math

Developers write in Markdown constantly: README files, architecture docs, API references, post-mortems, design proposals, onboarding guides. Most of that content lives and dies in a repository. But when it needs to leave — for a client presentation, a design review, a printed handout at a conference — a Markdown file by itself is not enough.

PDF is the format that travels without breaking. This guide covers exactly how to export developer-grade Markdown to PDF: code blocks with syntax highlighting, KaTeX math, GFM tables, and task lists, all formatted for print.

What Makes Developer Markdown Different

A standard Markdown-to-PDF tool handles paragraphs, headings, and lists. Developer Markdown adds several layers that most converters get wrong:

Fenced code blocks need language-aware syntax highlighting that prints cleanly. Highlighted HTML in a PDF looks professional. Plain monospace text looks like a draft.

Math equations appear in data science notebooks, algorithm documentation, and systems papers. They need a proper typesetting engine — not a screenshot, not LaTeX passthrough, but real rendered HTML that prints crisply.

GFM tables with many columns need correct overflow handling and print-safe rendering so they do not get cut off at the right margin.

Task lists need checkbox rendering, not bullet points. A printed sprint checklist or code review list loses its meaning if all checkboxes look identical.

The ShellPDFs Markdown to PDF converter handles all of these correctly. Here is how each feature works.

Syntax-Highlighted Code Blocks

The converter uses highlight.js with language autodetection enabled. Any fenced code block with a language identifier renders with full syntax highlighting:

```typescript
type Invoice = {
  id: string;
  total: number;
};

export function formatInvoice(invoice: Invoice) {
  return `#${invoice.id} — $${invoice.total.toFixed(2)}`;
}
```

Language support includes TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, SQL, Bash, YAML, JSON, Dockerfile, and 170+ others. If no language is specified, highlight.js attempts autodetection.

In the exported PDF, code blocks render with a light background (#f6f8fa, matching GitHub), monospace font, and correct font sizing. break-inside: avoid prevents code blocks from being split across pages unless they exceed a full page in length.

Tip for long code blocks: If a block is longer than one page, PDF print engines will break it. Add a comment dividing the block into logical sections, then separate them with a short paragraph explaining the split. The resulting PDF reads more cleanly than a single broken block anyway.

KaTeX Math Rendering

Inline math is wrapped in single dollar signs. Block math uses double dollar signs on their own lines:

Euler's identity: $e^{i\pi} + 1 = 0$

The Fourier transform:

$$
\hat{f}(\xi) = \int_{-\infty}^{\infty} f(x)\, e^{-2\pi i x \xi}\, dx
$$

Both render using KaTeX's HTML output, which uses precisely-positioned <span> elements with exact font metrics. The result is identical to GitHub's math rendering but now in a portable PDF.

KaTeX supports a broad subset of LaTeX math including fractions, integrals, summations, Greek letters, matrices, aligned environments, and custom operators. For a full list, see the KaTeX documentation.

Common math rendering issue: If your equations show as raw $...$ text, check that the page fully loaded before typing. KaTeX requires its CSS to initialize. A full page reload (Ctrl+Shift+R) resolves this in all known cases.

GFM Tables

Pipe tables render with correct alternating row shading and print-safe styles:

| Component     | Responsibility       | Latency target |
| ------------- | -------------------- | -------------: |
| API Gateway   | Auth + rate limiting |          < 5ms |
| Queue Worker  | Job processing       |         < 30 s |
| Storage Layer | File TTL + cleanup   |         < 50ms |

Right-aligned numeric columns use : on the right side of the separator. The converter preserves this alignment in both preview and PDF output.

Wide tables with many columns may exceed the page width. Options for handling this:

• Abbreviate column headers
• Remove lower-priority columns
• Switch to Legal paper size (wider page)
• Use HTML directly inside the Markdown for more control (the converter supports safe inline HTML)

Task Lists

GitHub Flavored Markdown task list syntax renders correctly:

- [x] Write architecture proposal
- [x] Get sign-off from infra team
- [ ] Implement feature flag
- [ ] Run load test
- [ ] Ship to production

Checked and unchecked checkboxes render as filled and empty boxes in the PDF — not as [x] and [ ] plain text. The list indentation and spacing matches the preview exactly.

Exporting a README as a PDF

Repository README files are the most common developer Markdown to convert to PDF. Here is the cleanest workflow:

1. Copy the README content from GitHub or your editor, or download the .md file.
2. Paste or upload to the Markdown to PDF converter.
3. Review the preview. Relative image paths (./docs/diagram.png) will not resolve — replace them with absolute URLs or embedded base64 images if the images matter for the PDF.
4. Select A4 or Letter paper size.
5. Export the PDF.

Handling relative image links: Relative paths do not resolve in a browser-based converter because there is no repository filesystem context. Use HTTPS URLs from your Git host's raw content endpoint, or embed the image using the "Embed Image" button to convert it to a base64 data URL inline in the Markdown.

Architecture and Design Docs

For architecture decision records, RFC documents, and technical proposals that combine prose, diagrams, code, and equations:

• Use H2 and H3 headings to create logical sections that print as a navigable document
• Block math for complexity analysis (Big O notation, recurrence relations)
• Code blocks for pseudocode, interface definitions, or configuration examples
• Tables for comparison matrices (database options, service tiers, latency budgets)

These documents often include the date and version at the top. Add it as the first paragraph before the first heading so it appears prominently in the PDF without requiring a separate title page.

Large Documents and Web Worker Rendering

Documents over 1 MB are automatically processed in a background Web Worker. This matters for:

• Long documentation sets (50+ pages of detailed Markdown)
• Documents with many embedded base64 images
• Content with extensive code fences or math

The Web Worker renders the Markdown to HTML off the main thread, so the editor remains responsive while rendering runs. A 15-second timeout prevents hung renders from blocking the UI indefinitely. If the timeout fires, the error appears in the preview and you can retry.

For documents in the 500 KB–1 MB range (which stay on the main thread), the 300ms debounce on the editor prevents excessive re-renders during typing.

The Export Pipeline in Detail

For developers who want to understand what is happening under the hood:

1. The unified processor runs remark-parse → remark-gfm → remark-math → remark-rehype → rehype-katex → rehype-highlight → rehype-stringify.
2. The resulting HTML is passed through DOMPurify with a custom afterSanitizeAttributes hook that validates link protocols and image sources.
3. The sanitized HTML is rendered into the preview via dangerouslySetInnerHTML.
4. On PDF export, the sanitized HTML is injected into an isolated srcdoc iframe along with the @page CSS for the selected paper size, the KaTeX stylesheet, and the syntax highlighting styles.
5. The browser waits for all images and fonts in the iframe to load, then calls print() on the iframe's window.
6. The iframe is removed from the DOM when the print dialog closes.

The result is a PDF that contains only your document. The editor, toolbar, and page layout are never captured.

Choosing the Right Paper Size for Developer Docs

A4 is the international standard and the right default for anything shared globally or submitted to European clients.

Letter is the US standard. Use it for anything shared within US organizations or printed on US letter paper.

Legal (8.5 × 14 in) is wider and taller than Letter. It is useful for wide tables that overflow on Letter, or for technical specifications with side-by-side comparisons.

For internal documentation that will only be read on screen, paper size matters less — A4 tends to produce a slightly narrower text column that is easier to read as a standalone document.

From README to Deliverable

The ShellPDFs Markdown to PDF converter is designed for the case where you already have Markdown and need a PDF — not for authoring from scratch in a rich editor.

It is particularly well-suited for:

• Converting a repository README into a client-facing overview
• Exporting a technical spec for a design review
• Printing a post-mortem or incident report from internal docs
• Generating a PDF of an onboarding guide or runbook
• Sharing engineering notes with math and code to a non-developer audience

No upload, no account, no server. The entire conversion runs in the browser.