Markdown Formatting Tips for Professional PDFs

Well-formatted Markdown produces well-formatted PDFs. This guide covers the techniques that make the biggest difference in your final output — from heading structure to table design to code block styling.

Heading Hierarchy Matters

Your heading structure determines the document outline. Use a logical hierarchy:

# Document Title (h1)
## Major Section (h2)
### Subsection (h3)
#### Detail Level (h4)

Tips:

• One h1 per document — it becomes the PDF title.
• Use h2 for main sections (Introduction, Methods, Results, Conclusion).
• Use h3 for subsections within each section.
• Avoid skipping levels (h2 → h4 without h3).

The Executive, Academic, and Legal templates use numbered headings, so proper hierarchy creates an automatic table of contents structure.

Tables That Look Great

Tables are one of the most powerful features. Here’s how to make them work well in PDFs:

| Project | Status | Budget | Lead |
| --- | --- | --- | --- |
| Website Redesign | In Progress | $45,000 | Alice |
| Mobile App | Planning | $30,000 | Bob |
| API Migration | Complete | $15,000 | Carol |

Tips:

• Keep column labels short: Long headers create wide columns that may overflow.
• Use alignment colons: :--- for left, :---: for center, ---: for right.
• Limit to 4-5 columns: More columns become hard to read on A4/Letter paper.
• Avoid merged cells: Standard Markdown tables don’t support cell merging.
• Preview before exporting: Wide tables may need shorter labels.

Code Blocks with Syntax Highlighting

Fenced code blocks with language labels get syntax highlighting in the PDF:

```python
def calculate_growth(revenue: list[float]) -> float:
    """Calculate quarter-over-quarter growth rate."""
    if len(revenue) < 2:
        return 0.0
    return (revenue[-1] - revenue[-2]) / revenue[-2] * 100
```

// Supported languages include:
// python, javascript, typescript, bash, sql, json, yaml,
// html, css, rust, go, java, cpp, and many more

Tips:

• Always include a language label — it enables syntax highlighting.
• Keep code blocks under 50 lines for best PDF pagination.
• Use inline code for short references, fenced blocks for multi-line code.

Images in Your PDFs

![Company Logo](https://example.com/logo.png)

Requirements:

• Images must be publicly accessible URLs (not local files).
• Supported formats: PNG, JPEG, WebP.
• Images auto-scale to fit the page width.

Tips:

• For logos in custom templates, use the image upload feature instead of Markdown images.
• Keep images under 2 MB for fast rendering.
• Use descriptive alt text — it appears if the image fails to load.

Blockquotes for Callouts

> **Key Finding**: Revenue grew 15% year-over-year, exceeding our Q3 projection by 3 percentage points.

Blockquotes render with a left border and indentation. Use them for:

• Key findings or takeaways
• Customer quotes or testimonials
• Important notes or warnings
• Excerpts from external sources

Lists — Bulleted and Numbered

### Key Deliverables

- Q4 Marketing Plan
  - Social media calendar
  - Email campaign schedule
- Budget Allocation
  - Departmental breakdowns
  - Contingency reserve

### Action Items

1. Review draft with stakeholders
2. Incorporate feedback by Friday
3. Submit final version for approval
4. Archive previous versions

Tips:

• Use bulleted lists for unordered items.
• Use numbered lists for sequential steps.
• Nest lists up to 3 levels deep.
• Leave a blank line before and after lists for proper spacing.

Links and References

See the [API documentation](https://markdowntopdfconverter.com/api-docs) for details.

For questions, contact [support@example.com](mailto:support@example.com).

Links are clickable in the PDF. Use descriptive link text — avoid “click here.”

Mermaid Diagrams

```mermaid
graph TD
    A[User] --> B[Markdown Input]
    B --> C[Template Selection]
    C --> D[Live Preview]
    D --> E[PDF Export]

Mermaid diagrams render as vector graphics in the PDF. Supported types: flowcharts, sequence diagrams, Gantt charts, class diagrams, state diagrams, pie charts, and more. Mermaid rendering requires a premium plan.

## Document Structure Checklist

Before exporting, verify:

- [ ] One h1 title at the top
- [ ] Logical heading hierarchy (h1 → h2 → h3)
- [ ] Tables have consistent column counts
- [ ] Code blocks have language labels
- [ ] Images have descriptive alt text
- [ ] Links use descriptive text
- [ ] Lists have blank lines before and after
- [ ] No HTML tags (use pure Markdown)

## Next Steps

- Try these techniques in the [converter](/convert) with live preview.
- Learn how to design a [custom template](/learn/custom-template-guide) that uses your brand's typography.
- Compare [all six templates](/learn/template-comparison-guide) to find the right one for your content.