beautiful-markdown-for-pdf-export

name	beautiful-markdown-for-pdf-export
description	Guidelines and instructions for generating Markdown that looks excellent when read natively and renders beautifully when exported or converted to PDF. Use when this capability is needed.
metadata	{"author":"403errors"}

Beautiful Markdown for PDF Export

When generating Markdown files that will ultimately be read by humans or converted into PDF documents (e.g., via browser print to PDF, Pandoc, or other generators), it is essential to follow specific structural and formatting guidelines. Standard markdown can look plain or break awkwardly across pages if not formatted with intent.

Core Principles

1. Clear Hierarchy: Use progressive header levels (#, ##, ###) without skipping levels. This ensures a clean Table of Contents is generated by PDF parsers.
2. Whitespace is Magic: Always include ample blank lines between different elements (headers, paragraphs, lists, and code blocks). This prevents elements from crowding and allows PDF engines to calculate page breaks more gracefully.
3. Use Tables for Structured Data: When presenting key-value pairs, summaries, or specs, prefer Markdown tables over bullet points. Tables render beautifully with clear borders in PDFs.
4. Avoid Deep Nesting: Deeply nested lists (more than 2 levels) or blockquotes within blockquotes often render poorly in PDFs, causing severe margin squishing. Keep the structure flat.
5. Bold for Scannability: Use **bold** text to highlight key terms at the start of bullet points or inside paragraphs, acting as miniature sub-headers.

Practical Directives