A Markdown to PDF request, read line by line
Nine lines of a request, then nine blocks of a Markdown file, each opened to show what it did to the PDF. Pick a line to read its note. Every note about the PDF comes from a run on 10 November 2026.
- 4 works
- 3 breaks
- 1 surprise
- 1 check
The request
One command sends a file called report.md and saves the answer. Run it on your server, never in a web page, because the key must stay private.
- Check
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.
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.
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
This is report.md. The left edge colour is the verdict: green worked, red broke, amber surprised, grey is worth a check. The converter is marked 18.0.14 with GitHub-flavoured Markdown on.[1]
- 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.
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.
The figures are for this setup
styles value or a different font can change a cut-off point. Read the HTML and Markdown input page for the rules the service states.Where the page ends
A heading and its paragraph were printed after 20 to 52 paragraphs of filler, 33 lengths in all. Each square is one length. Red means the heading was alone at the foot of a page and its paragraph started the next.
No fix
4 of 33 lengths
- 20
- 21
- 22 heading alone
- 23 heading alone
- 24 heading alone
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51 heading alone
- 52
h1, h2, h3 { break-after: avoid }
0 of 33 lengths
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
A code block of 6 lines was split between two pages in 0 of the same 33 lengths, so a short block stays whole without help. For other print rules, such as repeating a table header, see the invoice recipe.
Before and after
Seven measurements, each read back from the PDF. The fix column is a single rule or a single line of the file.
| 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 fix, in one field
Three rules go in the styles option, in the same JSON as markdown. A title tag and a heading with an id go in the file.
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, so check your own file once. In jq, add a line styles: $css, and a second --rawfile css fix.css. A render is one screenshot of your plan: the Free plan has 100 a month and needs no card. See the plans.
- Works
The only thing that sets the PDF title
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
Set pdf_margin for the white border you want, and count the 42 pt of padding as part of it.
- Breaks
A link to a heading goes nowhere
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
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
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
Add pre { white-space: pre-wrap; overflow-wrap: anywhere } in the styles option: 200 of 200 characters at 0, 10 and 20 mm.
- Check
A relative image path is kept as written
Use a full address, or a data: address for a small picture.
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.
A code line counted as cut when fewer of its characters were in the PDF than in the file. A table cell counted as cut the same way, by letters. A heading counted as alone when it and the paragraph after it were on different pages. A link counted when the PDF held a link annotation for it.
What the test did not cover: the API of this service. The request is written from the documentation and the options code, and it was not sent. The task-list, strikethrough and image notes were read in the converted page, not in the PDF.
Questions people ask
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). Checked .
Read next
- Recipe cardInvoice PDF from HTML: a recipe cardAn 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.
- ReferenceWeb page to PDF: paper sizes, margins, print CSSPaper 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.
- Myth listSix screenshot myths, tested in ChromiumSix beliefs about website screenshots, run through Chromium on test pages: width, height, retina size, transparency, full page and repeatability.