Exporting documents

This page is a real markdown document, and the app beside it exports this page. Everything below is here to be printed: a handful of headings so the table of contents has something to build, a table, a list, a code block, and enough prose to spill onto a second page. Export it and compare the PDF with what you are reading.

The three formats

Export is one pipeline with three renderers. They are not interchangeable, and picking the wrong one is the commonest disappointment:

Format	What it is for	The thing to know
PDF	The artifact you send someone — a report, a proposal, a printed deck.	Printed by the headless browser from the same HTML the page renders, so a cover page, a running header and a real table of contents come with it.
DOCX	A document someone has to keep editing.	Real Word structure — headings, lists, tables — not a PDF in a wrapper. It renders the node's own body, so a node with no markdown body produces an empty file.
HTML	The BODY of an email, not an attachment.	Inline CSS only, table-based layout, absolute URLs, no script — and the one format that resolves embedded live layout areas into static markup.

The table of contents is measured, not guessed

A contents entry has to carry the page number the reader will actually turn to, and no browser implements CSS target-counter. So the pipeline prints the document, reads the page numbers back out of the printed PDF's own link annotations, and prints it again with the real numbers in place. That is why the contents in an exported PDF agrees with the document, and why a hand-rolled "page 1, page 2…" never does.

What the options change

The dialog is small on purpose. These are the choices that alter the document rather than its metadata:

Cover page — a branded first page. Off for something that will be pasted into another document.
Table of contents — inserted after the cover, or at the top when there is no cover.
Page break before each heading — # by default, ## optionally. This is what turns a long page into chapters.
Include children — the node's descendants follow as successive chapters, optionally to a bounded depth. This is how a whole section of a handbook becomes one file.
Branding — point at a CorporateIdentity node and its logo, header and footer are used. Empty means the portal's own defaults.
Landscape — for wide tables and 16:9 slides.

Fidelity — content or pixel

Most documents want content fidelity: the markdown is reconstructed into a document model and composed into a structured print document. The text is selectable, the file is small, and the cover, contents and running header exist at all — none of which survive a screenshot.

Pixel fidelity exists for the one case content fidelity cannot serve: a slide deck whose meaning is carried by CSS the document model has no way to express — gradients, image backgrounds, raw HTML slide bodies, transforms, web fonts. It composes the deck's own live stage and prints that. It applies to decks only, and the option appears only when the server can resolve a headless browser.

Print templates are files

The PDF's HTML and CSS are real .html and .css files embedded in the module, not strings built up in C#. So a deployment that wants a different cover, a different running header or different table rules edits a stylesheet rather than a renderer.

Templates/Export/Pdf     the script that composes and prints the document
Templates/Export/Docx    the Word renderer
Templates/Export/Html    the email-safe renderer

Those are ordinary mesh nodes, and an export is an ExecuteScriptRequest against one of them — which is why an export shows up as an Activity you can watch, rather than a request that blocks until it finishes.

What is not exported

Worth knowing before you send the file to someone:

Live layout areas are static in PDF and DOCX — they carry no reader and no live data. Only the HTML format resolves them into markup.
A node with no markdown body contributes an empty chapter. When you include children, most descendants of a typed-content node are simply not chapters, and are skipped rather than printed blank.
Access travels with the reader, not the file. An exported document is a copy: once it leaves the mesh nothing re-checks who may read it.