Markdown to PDF Conversion at PodPDF

Markdown has become the de-facto format for technical writing, documentation, README files, and content pipelines. Converting it to a well-formatted PDF is a natural next step — but the tooling to do it well has historically been awkward. PodPDF handles Markdown natively, without any intermediate conversion step on your side.

Why Markdown → PDF Conversion Is Harder Than It Looks

On the surface, Markdown is simple. In practice, producing a polished PDF from Markdown requires several things to work correctly:

1. Parsing — The Markdown must be parsed according to a spec with consistent behavior
2. Rendering — The parsed content must become styled HTML
3. Layout — Page breaks, margins, headers, footers, and page numbers must be handled
4. Typography — Code blocks, tables, blockquotes, and inline code all need distinct styling
5. Images — Referenced images must be fetched and embedded correctly

Most DIY approaches solve some of these but not all. You end up with code blocks that overflow pages, tables that break mid-row, or images that don’t load.

How PodPDF Handles Markdown

When you send Markdown to PodPDF, the pipeline works like this:

1. Parse — Markdown is parsed with GitHub Flavored Markdown (GFM) enabled: tables, strikethrough, task lists, and autolinks
2. Convert to HTML — The parsed content is rendered into HTML with a clean default stylesheet for body text, code, and tables
3. PDF rendering — The HTML is rendered using a modern headless browser engine, which handles layout, pagination, and typography

Supported Markdown Features

• Headings (H1–H6)
• Bold, italic, strikethrough, and inline code
• Ordered and unordered lists, including nested lists
• Task lists (- [x] done)
• Tables with header rows
• Blockquotes
• Fenced code blocks
• Links
• Images (from absolute URLs)
• Horizontal rules

API Usage

Via the REST API

Send Markdown to POST /quickjob with your API key in the X-API-Key header. input_type tells PodPDF what the content is:

curl -X POST https://api.podpdf.com/quickjob \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_type": "markdown",
    "markdown": "# My Report\n\nThis is a paragraph.\n\n## Section 1\n\n- Item one\n- Item two",
    "options": {
      "format": "A4",
      "margin": { "top": "20mm", "bottom": "20mm", "left": "20mm", "right": "20mm" }
    }
  }' \
  --output report.pdf

By default the response is the PDF — binary, with Content-Type: application/pdf — so --output saves it straight to a file. The X-PDF-Pages header tells you the page count.

If you’d rather get a link, add "store": true. The response becomes JSON:

{
  "job_id": "9f0a4b78-2c0c-4d14-9b8b-123456789abc",
  "pages": 3,
  "truncated": false,
  "download_url": "https://...",
  "download_url_expires_at": "2026-04-18T11:30:00.000Z"
}

The download_url is valid for one hour. The file is kept for 30 days, and you can get a fresh link at any time with GET /jobs/{job_id}/download.

/quickjob returns documents up to 25 pages within 30 seconds. For longer documents, use POST /longjob (up to 100 pages, asynchronous).

Via the Web App

You can paste or upload Markdown directly in the PodPDF web app without writing any code. Upload a .md file or paste raw Markdown, set page format, orientation and margins, and download the result.

Customizing the Output

Page format and margins

{
  "input_type": "markdown",
  "markdown": "...",
  "options": {
    "format": "Letter",
    "margin": {
      "top": "25mm",
      "bottom": "25mm",
      "left": "30mm",
      "right": "30mm"
    }
  }
}

Landscape orientation

{
  "options": {
    "format": "A4",
    "landscape": true
  }
}

Headers and footers

{
  "options": {
    "displayHeaderFooter": true,
    "headerTemplate": "<div style='font-size:10px; margin: 0 auto;'>My Company — Confidential</div>",
    "footerTemplate": "<div style='font-size:10px; margin: 0 auto;'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>",
    "margin": { "top": "25mm", "bottom": "25mm" }
  }
}

Leave room in the top and bottom margins for headers and footers — there’s no default margin, so without one they’ll overlap the content.

Converting Many Markdown Files at Once

If you have a folder of Markdown — a docs site, a set of reports — you don’t need to call /quickjob in a loop. Bulk conversion takes a ZIP of .md files and returns a ZIP of PDFs. Images referenced by relative path inside the bundle work there too, which they can’t in a single-document request.

Common Use Cases

Technical documentation

Convert docs written in Markdown to PDFs for offline distribution, client deliverables, or archival.

README files

Turn your repository’s README directly into a shareable PDF — useful for proposals, open-source project summaries, or onboarding packets.

Reports and summaries

Generate reports from Markdown templates, merging in data before sending to PodPDF. This works well in automation pipelines where report templates are stored as Markdown.

Meeting notes and changelogs

Convert Markdown-formatted meeting notes, changelogs, or release notes into PDFs for records management or email distribution.

Tips for Better PDF Output

Use ATX-style headings (# H1, ## H2) rather than setext-style (=== underlines) — they’re easier to read and less ambiguous.

Keep tables simple — Markdown tables don’t support merged cells. Use them for tabular data, not layouts.

Use absolute URLs for images — In a single-document request, relative image paths have nothing to resolve against. Use full https:// URLs, or use bulk conversion and ship the images in the same ZIP.

Want more styling control? Convert your Markdown to HTML yourself and send it with input_type: "html" and your own stylesheet.

Test with real content — Use real-world Markdown rather than synthetic examples to catch edge cases early.

Getting Started

Create a PodPDF account and buy credits — $0.01 per PDF, and credits never expire. The API documentation has the full reference for all Markdown conversion options.