Skip to content
Annotated requestBy 7 min read

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.

  1. 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.

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]

  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 figures are for this setup

A4 pages, the converter's own style sheet and short files. Another paper size, a custom 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 measuredWithout a fixWith the fixThe fix
PDF title from a tag, a heading, front mattertag: set; heading: empty; front matter: empty and printedtag on line 1<title>Q3 report</title>
Characters of a 200-character code line, margin 0 / 10 / 20 mm80 / 71 / 62200 / 200 / 200pre { white-space: pre-wrap; overflow-wrap: anywhere }
Letters in a table of 8 columns of 14 (of 96)5796td, th { overflow-wrap: anywhere }
Letters in a table of 10 columns of 20 (of 179)62179td, th { overflow-wrap: anywhere }
Letters in a table of 12 columns of 14 (of 141)57141td, th { overflow-wrap: anywhere }
Link annotations for a link to a heading01<h2 id="results">Results</h2>
Headings alone at the foot of a page, of 33 lengths40h1, 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.

styles
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.

Screenshot any page in one step

Paste an address into CurlShot and download the screenshot. A free account gives you 100 screenshots every month. No card needed.