# A Markdown to PDF request, read line by line

> One Markdown-to-PDF request, read line by line, with what each line does to the PDF: title, margins, code width, tables, links, footnotes, page breaks.

Annotated request by Serghei Pogor, founder of CurlShot (https://curlshot.com/about/serghei-pogor). Published 10 November 2026. Page for people: https://curlshot.com/blog/markdown-to-pdf-request-annotated

Send the Markdown in the markdown field of a POST request to CurlShot with format=pdf, then save the answer as a .pdf file. Four things the converter does not do for you: it sets no PDF title unless the file holds a title tag, it does not wrap code lines, it gives headings no ids so links to them go nowhere, and it has no footnotes. In a test on 10 November 2026 each one had a fix of a single line.

## Key facts

- Only a title tag sets the PDF title. In the test of 10 November 2026 a Markdown heading left the Title field empty, and front matter was printed on the page as text.
- The text starts 42 pt from the left edge even when pdf_margin is at its default of 0. A margin of 10 mm moved it to 69.7 pt.
- A code line is cut, not wrapped: of 200 characters, 80 reached the PDF at margin 0 and 62 at 20 mm. One rule in the styles option brought all 200 through.
- Links to full addresses are clickable in the PDF, links to a heading are not, because headings have no ids. A raw heading tag with an id fixed it. Footnotes print as typed.
- A heading ended up alone at the foot of a page in 4 of 33 document lengths, and in none with break-after: avoid. One render counts as one screenshot of the plan of CurlShot.

## The request, line by line

```bash
jq -n --rawfile md report.md '{
  markdown: $md,
  format: "pdf",
  pdf_paper_format: "a4",
  pdf_margin: "10mm"
}' |
  curl -X POST "https://curlshot.com/api/v1/screenshot" \
    -H "X-Access-Key: $ACCESS_KEY" \
    -H "Content-Type: application/json" \
    -d @- \
    --output report.pdf
```

- **Let jq build the JSON.** The Markdown holds quotes, line breaks and backslashes, which JSON must escape. --rawfile reads the whole file as one string, and jq escapes it. It needs jq on the machine that runs the request; in code, JSON.stringify does the same.
- **The markdown field.** Send one source: url, html or markdown. Two at once are refused with "only one of `url`, `html` or `markdown` can be used". The limit is 2 MB. The conversion has a 5 second deadline; an input with long runs such as "*a *a *a" is refused with "markdown: took too long to convert" (both messages are from the source code, not run here). The converter is marked 18.0.14 with GitHub-flavoured Markdown on.
- **The format.** Without it the answer is a PNG of the same styled page. The pricing page lists async renders, webhooks, bulk and signed links as paid only (read 2026-11-10); PDF is not on that list, so it works on the Free plan.
- **The paper.** a4 is the default, so this line only states it. Use letter for US paper. An A4 page in the test PDFs was 595.9 pt wide.
- **The margin.** The default is 0. A margin that leaves no room on the page is refused. The converter's own padding of 42 pt comes on top, so this request puts the text about 70 pt from the edge (69.7 pt measured).
- **One call, one screenshot.** A successful render counts as one screenshot of the plan, whatever the page count. Failed renders and cache hits are free. The Free plan has 100 a month and needs no card (pricing page, read 2026-11-10).
- **The key stays on your server.** Run this from a server or a job, never in a web page, so the key is not public. It lives in a variable here, not in the file.
- **The body comes from the pipe.** -d @- reads the body from standard input, which is the JSON that jq printed.
- **Check before you trust the file.** A refusal is JSON, not a PDF, and --output would write it to report.pdf all the same. A real PDF starts with the four characters %PDF, so check them, or the status code, before you pass the file on.

This request follows the documentation and was not sent in this run: the lab host has no access key. The notes about the PDF come from the lab below; the notes about the request come from the options code and the pricing page.

## The document, block by block

````markdown
<title>Q3 report</title>

# Quarterly report

Read the [summary](https://example.com/q3) first.
Paste https://example.com/q3 as a bare address too.

Jump to [the results](#results).

## Results

Revenue grew 12%.[^1]

[^1]: Audited, 2026.

| Region | Q3 | Share |
| --- | --- | --- |
| EMEA | 1,204,330 | 41% |

```bash
curl -s "https://api.example.com/v2/orders?status=open&limit=100&sort=created_at&fields=id,total" -o orders.json
```

- [x] Reviewed
- [ ] Signed

~~draft~~ final

![Logo](img/logo.png)
````

- **Works: The only thing that sets the PDF title.** The converter writes no title of its own. With this tag in the file the PDF's Title field read "Q3 report". With only a "# Quarterly report" heading the Title field was empty. With front matter (--- title: ... ---) it stayed empty and the line "title: ..." was printed at the top of page 1 as text. Fix: Put a title tag on the first line of the file.
- **Surprise: A heading does not name the file, and the text does not start at the edge.** The heading is styled with a rule underneath, but it is only text on the page. The text also starts 42 pt (56 px) from the left edge of the paper while the margin is still at its default of 0, because the converter wraps the page in padding. With pdf_margin 10 mm the left edge of the text was at 69.7 pt, and with 20 mm at 98.2 pt. Fix: Set pdf_margin for the white border you want, and count the 42 pt of padding as part of it.
- **Works: Full addresses become links in the PDF.** Both the Markdown link and the bare address came out as clickable link annotations: 2 of 2. The converter turns a bare address into a link on its own.
- **Breaks: A link to a heading goes nowhere.** The converted page gives no heading an id, so "#results" has no target. The PDF held no link annotation for it at all: only the 2 full-address links from the lines above. The parser dropped heading ids in version 8, and they come back only with an extension [1]. Fix: Write the heading as a raw tag, <h2 id="results">Results</h2>. In the test, a link to #target with <h2 id="target"> gave 1 link annotation with that destination.
- **Breaks: Footnotes print as the raw text you typed.** The PDF held "Revenue grew 12%.[^1]" and a separate line "[^1]: Audited, 2026." Footnotes need an extension of the parser [1], and the converter does not load one. Fix: Write the note in the text, or end the file with a plain list called Notes.
- **Works: A table shrinks to the page, until a cell cannot break.** Tables of 3, 5, 6, 7 and 9 columns with cell text that can break at a hyphen showed every cell. Cells with no place to break did not fit: with 8 columns of 14 letters the PDF held 57 of the 96 letters, with 10 columns of 20 letters 62 of 179, and with 12 columns of 14 letters 57 of 141. The rest was cut at the right edge without an error. Fix: Add td and th { overflow-wrap: anywhere } in the styles option: all 96, 179 and 141 letters came through.
- **Breaks: A code line is cut, not wrapped.** A code line of 200 characters reached the PDF with 80 of them at margin 0, 71 at 10 mm, 66 at 15 mm and 62 at 20 mm. The rest was cut without a sign. Code blocks that are tall are fine: 300 lines came through whole, over 7 pages. Fix: Add pre { white-space: pre-wrap; overflow-wrap: anywhere } in the styles option: 200 of 200 characters at 0, 10 and 20 mm.
- **Works: Task lists and strikethrough are converted.** The converted page held 2 checkbox inputs and a del element. This one was read in the converted page, not in the PDF, so how a ticked box looks on paper was not checked.
- **Check: A relative image path is kept as written.** The converter kept the path "img/logo.png" unchanged in the page. The page is loaded from a string, so it has no address of its own to resolve a relative path against. A data: address is kept as written too. Fix: Use a full address, or a data: address for a small picture.

## The score

Works: 4, Breaks: 3, Surprise: 1, Check: 1 (of 9 blocks).

## Page breaks

Over 33 document lengths (20 to 52 paragraphs before a heading), the heading was alone at the foot of a page, with its paragraph on the next, at 22, 23, 24, 51 paragraphs: 4 of 33. With `h1, h2, h3 { break-after: avoid }` in the styles option, none. A code block of 6 lines was never split between two pages in the same 33 lengths.

## Before and after

| What was measured | Without a fix | With the fix | The fix |
| --- | --- | --- | --- |
| PDF title from a tag, a heading, front matter | tag: set; heading: empty; front matter: empty and printed | tag on line 1 | `<title>Q3 report</title>` |
| Characters of a 200-character code line, margin 0 / 10 / 20 mm | 80 / 71 / 62 | 200 / 200 / 200 | `pre { white-space: pre-wrap; overflow-wrap: anywhere }` |
| Letters in a table of 8 columns of 14 (of 96) | 57 | 96 | `td, th { overflow-wrap: anywhere }` |
| Letters in a table of 10 columns of 20 (of 179) | 62 | 179 | `td, th { overflow-wrap: anywhere }` |
| Letters in a table of 12 columns of 14 (of 141) | 57 | 141 | `td, th { overflow-wrap: anywhere }` |
| Link annotations for a link to a heading | 0 | 1 | `<h2 id="results">Results</h2>` |
| Headings alone at the foot of a page, of 33 lengths | 4 | 0 | `h1, h2, h3 { break-after: avoid }` |

The three style rules, for the styles field:

```css
pre { white-space: pre-wrap; overflow-wrap: anywhere }
td, th { overflow-wrap: anywhere }
h1, h2, h3 { break-after: avoid }
```

Each rule was tested alone. The three together were not run.

## How it was tested

On 10 November 2026, with Chromium 153.0.8010.12 driven by Playwright 1.63.0, the converter marked 18.0.14 with GitHub-flavoured Markdown on, and the PDFs read back with pdf.js (pdfjs-dist 6.5.438). Each case was a small Markdown file. It went through the renderer's own Markdown converter, was loaded into a page, printed to A4 with the same Chromium call the renderer uses (backgrounds on), and the PDF was read back: its Title field, the position of every text item, its link annotations and the page each line landed on. A fix was added the way the styles option adds it, as a style tag after the page loads, and the same case was read again. The API of CurlShot was not part of this test, and the request was not sent. The results are for A4 pages, this converter and these small files; other fonts and paper sizes may behave differently.

Start on the Free plan, which needs no card: see [pricing](https://curlshot.com/pricing). The Markdown field is described on [HTML and Markdown input](https://curlshot.com/docs/html-and-markdown), and the PDF options on [PDF rendering](https://curlshot.com/docs/pdf).

## Questions

### How do I set the title of a PDF made from Markdown?

Put a title tag on the first line of the Markdown, for example <title>Q3 report</title>. In a test on 10 November 2026 the PDF's Title field read "Q3 report" with the tag, and was empty with only a heading or with front matter.

### Why is my code block cut off in the PDF?

The converter does not wrap code lines, and a line that is too wide is cut at the page edge without an error. In the test, 80 of 200 characters survived at margin 0 and 62 at 20 mm. Add pre { white-space: pre-wrap; overflow-wrap: anywhere } in the styles option and all 200 came through.

### Do footnotes and links to headings work in Markdown to PDF?

Not as written. Footnote syntax prints as the raw text, and a link such as #results has no target because headings carry no ids [1]. A raw heading tag with an id, <h2 id="results">, gave a working link in the test.

### Why does a heading sit alone at the bottom of a page?

Chromium does not keep a heading with the text after it by default. It happened in 4 of 33 document lengths. The rule h1, h2, h3 { break-after: avoid } in the styles option removed all four.

### Is Markdown to PDF free to try?

Each successful render counts as one screenshot, and the Free plan of CurlShot has 100 a month without a card (read from the pricing page on 2026-11-10). The tool on the home page needs no account.

## Sources

1. Marked documentation, "Advanced options (headerIds removed in v8; the footnote extension)": https://marked.js.org/using_advanced (checked 10 November 2026)

## Go deeper

- [Markdown to PDF](https://curlshot.com/tools/markdown-to-pdf)
- [HTML and Markdown input](https://curlshot.com/docs/html-and-markdown)
- [PDF rendering](https://curlshot.com/docs/pdf)
- [Pricing](https://curlshot.com/pricing)

## Read next

- [Invoice PDF from HTML: a recipe card](https://curlshot.com/blog/invoice-pdf-from-html.md): An invoice from HTML to an A4 PDF in one request: the HTML, the call, and a test of 41 invoices that shows which print CSS rules matter.
- [Web page to PDF: paper sizes, margins, print CSS](https://curlshot.com/blog/web-page-to-pdf-paper-sizes.md): Paper sizes in millimetres, inches, CSS pixels and points, how margins and page breaks work in a PDF of a web page, and the print CSS that controls them.
- [Six screenshot myths, tested in Chromium](https://curlshot.com/blog/screenshot-myths-tested.md): Six beliefs about website screenshots, run through Chromium on test pages: width, height, retina size, transparency, full page and repeatability.
