PDF Export Tips for Perfect Output

Exporting to PDF is more than clicking a button. A few small adjustments to your Markdown and settings can mean the difference between a polished, professional document and one with orphaned headings, clipped images, or inconsistent spacing. This guide covers the most important tips.

Tip 1: Use a Clear Heading Hierarchy

The PDF renderer uses your heading structure to determine page flow. A clean hierarchy (H1 → H2 → H3) ensures headings and their content stay together on the page, avoiding situations where a heading appears at the very bottom of a page with its content on the next.

Tip 2: Avoid Extremely Wide Tables

Tables that are too wide for the page area are clipped or scaled down unexpectedly. If your table has many columns, consider:

• Removing less important columns and referencing the full data in an appendix
• Transposing the table (swap rows and columns) if there are many attributes but few items
• Using a narrower column format with shorter text in each cell

Tip 3: Control Image Sizing

Images default to their natural size but are capped at the page width. For best results, keep source images between 800px and 1600px wide. Very small images can appear blurry when the PDF renderer upscales them.

To explicitly cap an image’s width inline:

<img src="./chart.png" alt="Quarterly chart" style="max-width: 60%;" />

Tip 4: Force Page Breaks with HTML

You can insert an explicit page break using a raw HTML div:

<div style="page-break-after: always;"></div>

Place this after any section where you want a new page to begin — useful for separating major chapters or putting an appendix on a fresh page.

Tip 5: Avoid Page Breaks Inside Code Blocks

Long code blocks can be split across pages in an unreadable way. If a code block is longer than half a page, consider:

• Breaking it into smaller chunks with explanatory text in between
• Adding a page break before the code block so it starts at the top of a fresh page

Tip 6: Keep Paragraphs to 3–5 Sentences

Very long paragraphs increase the likelihood of awkward page splits mid-paragraph. Keeping paragraphs short also improves readability and gives the renderer more natural break points.

Tip 7: Use Tables for Structured Comparisons

When you have structured data that would otherwise be a long bulleted list, a table renders much more compactly and clearly in PDF:

| Option | Pros | Cons |
|--------|------|------|
| A      | Fast | Expensive |
| B      | Cheap | Slow |

Tip 8: Enable the Table of Contents for Long Documents

For documents longer than 3–4 pages, enable the TOC toggle. This adds a navigable TOC in the HTML share view and a structured contents section at the start of the PDF.

Tip 9: Check Diagrams Before Exporting

Diagrams (Mermaid, PlantUML, etc.) are rendered server-side before PDF generation. If a diagram fails to render, its source text will appear instead. Always verify diagrams render correctly in the preview before exporting.

Tip 10: Use the Shared Link for Review

Before sending a PDF, share the document link with reviewers. They can view the HTML version in their browser — which is faster to load and fully interactive — and you can regenerate the PDF after incorporating feedback, saving time and avoiding unnecessary PDF emails.

Common Problems and Fixes