tomevault-io 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
- Clear Hierarchy: Use progressive header levels (
#,##,###) without skipping levels. This ensures a clean Table of Contents is generated by PDF parsers. - 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.
- 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.
- 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.
- 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
1. The Title Section
Always start with an H1 (#) followed by a brief meta-data section (e.g., Date, Author, Context).
# Security Scan Report: repo-owner/repo-name
**Generated:** October 26, 2026
**Analyzer:** RepoMind Security Bot
**Depth:** Deep Analysis
---
Note: The horizontal rule (---) acts as a visual separator that translates well to a solid line in PDF.
2. Summary Blocks
Use Blockquotes (>) for executive summaries or high-level status updates. PDF renderers usually style these with a distinct background or border color.
> **Executive Summary**
> The codebase contains **2 Critical** and **4 High** severity issues.
3. Presenting Findings or Issues
For recurring items (like security findings), use a consistent, repeating structure involving H3s (###) and definition lists.
Format template:
### 🔴 [CRITICAL] SQL Injection Risk in User Handler
- **Location**: `src/api/users.ts` (Line 42)
- **Type**: Parameter Tampering
- **Status**: Vulnerable
**Description**
User input is concatenated directly into the database query string without sanitization.
**Recommendation**
Use parameterized queries or prepared statements provided by the ORM.
**Code Snippet**
\`\`\`typescript
const query = "SELECT * FROM users WHERE email = '" + req.body.email + "'";
db.execute(query);
\`\`\`
Why this works:
- Emojis (
🔴,🟠,🟡) serve as excellent visual anchors that translate perfectly to modern PDFs. - Short bulleted meta-data lists keep the layout tight.
- Dedicated paragraphs for Description and Recommendation separate the prose.
- Code blocks are clearly delineated.
4. Page Break Management
While standard Markdown doesn't have a native page break syntax, PDF renderers often respect HTML page breaks. If you need to force a page break before a new major section, insert:
<div style="page-break-before: always;"></div>
Only use this sparingly, usually right before large Appendices or between distinct logical chapters.
5. Code Block Constraints
- Keep lines inside code blocks under 80 characters if possible. Code blocks in PDFs do not horizontally scroll; they wrap (which looks ugly) or clip (which loses data).
- Always include the language identifier for syntax highlighting (e.g.,
\``javascript`).
The Golden Rule for Repomind Reports
When taking StoredScan data and generating Markdown, do not just dump the JSON. Synthesize it using the templates above so that when the user clicks "Download Markdown" and subsequently attempts to print the page, the resulting artifact looks like a professionally authored report rather than a terminal output dump.
Source: 403errors/repomind — distributed by TomeVault.