A big Markdown file should become a PDF you can navigate

A Big Markdown File Should Become a PDF You Can Navigate | Artem DemchyshynA Big Markdown File Should Become a PDF You Can Navigate Convert a long Markdown document to PDF and it becomes something you move around in: a clickable bookmark outline, working [text](#heading) jumps, a page-numbered contents, bidirectional footnotes. Why that's the part most converters skip, and how it all falls out of a single idea — name an anchor now, let the engine bind it to a page after layout. 4 July 2026 · 9 min · Artem Demchyshyn Markdown becomes a PDF you can move around in — bookmarks, TOC, internal links, and footnotes.Table of ContentsWhy converters skip this The mapping is (almost) one line per heading The same move, four more times Why this lives below the converter, not in it The payoff

Update (July 2026). The first version of this post told one story — headings become a PDF bookmark outline. That’s still the heart of it, but the library grew a whole navigation layer since, and it just shipped to Maven Central as io.github.demchaav:graph-compose-markdown:0.3.0. So here’s the fuller picture: the outline, plus working [text](#heading) jumps, an auto-generated [TOC], a page-numbered book-style contents, and bidirectional footnotes — all the same idea applied five times.

Take a long Markdown file — a spec, a README that grew too big, a design doc with thirty sections. Convert it to PDF the usual way and you get a wall of pages. To find the deployment section you scroll, or you Ctrl+F, or you guess at a page number. The structure that was right there in your headings — #, ##, ### — is gone. It rendered as bigger, bolder text and nothing else. It shouldn’t be gone. Those headings are the table of contents. A PDF can carry a bookmark outline that the viewer shows in a side panel, nested exactly like your headings, every entry a clickable jump. Open the panel, click “Deployment,” you’re there. And that’s only the start of what a long document should give you: a [TOC] you can click, cross-references ([see deployment](#deployment)) that actually jump, footnotes that take you down to the note and back up. That’s the stuff almost every Markdown-to-PDF path drops on the floor. I wanted my converter to keep all of it. The repo is graphcompose-markdown: it parses Markdown with Flexmark, maps it to its own semantic model, and renders that through the GraphCompose engine to a PDF. The headline is simple to state — a long document becomes one you can move around in — and the interesting part is how little code each piece took, because they’re all the same trick. Why converters skip this# A PDF bookmark is not a heading. It’s an entry in a separate document outline tree that lives outside the page content — a node with a title and a destination (a page object plus coordinates), arranged in its own hierarchy that the viewer renders in the bookmarks panel. The same is true of an internal link: it’s a GoTo action pointing at a named destination, nothing to do with the text that triggers it. So to turn a heading into a bookmark — or a [text](#heading) into a real jump — you need three things a naive converter doesn’t have lying around at the right moment: The plain text of the heading. A heading like ## **Deploy** the service carries bold and code spans. The outline title has to read Deploy the service — markup stripped — or the panel shows raw asterisks and backticks. The page and position the heading landed on. You don’t know that until the document is laid out and paginated, which happens long after you’ve walked the Markdown. A stable name, and a nesting level. An h3 under an h2 under an h1 has to nest as a tree. And every heading needs an anchor — the same one a [link](#anchor) and a [TOC] entry will target — or nothing resolves. Most “md to pdf” tools render visually correct pages and stop. Everything above is extra plumbing against the PDF’s structure, decoupled from the text flow, and it’s easy to decide it’s not worth it. That’s the gap I cared about closing. The mapping is (almost) one line per heading# The trick is that the layout engine already solves the hard parts. GraphCompose owns measurement and pagination, and it supports a declarative bookmark on a container that resolves to the right page after layout — the author never touches coordinates. It also lets a paragraph declare a named anchor that other content can jump to. So the Markdown renderer only does the cheap part: pull the plain text, hand the heading level through as the outline depth, and name the anchor. Here’s the actual heading renderer, lightly trimmed to the navigation lines: public void render(HeadingNode node, SectionBuilder host, RenderContext ctx) { RichText rich = ctx.toRich(node.content(), ctx.headingInline(node.level())); String title = ctx.inline().plainText(node.content()).strip(); // markup stripped

// The slug this...

A big Markdown file should become a PDF you can navigate

Related Articles

(no title)

Is AI ruining our skills? Early results are in – and they're not good

The Anatomy of an AI-Native Org

ZCode – Harness for GLM-5.2

Apertus – Open Foundation Model for Sovereign AI