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:

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.
• Include linked documents (PDF and Word): every mesh document the export LINKS to is appended as a numbered appendix chapter, so a recipient who cannot open the portal still gets the content (MeshWeaver.Plugins#3707). Details:
  • Which links count. A link counts when it points at a mesh path: @/…, /…, a relative path resolved against the page's own path, or a native @Path link on its own line. Web links, images (and links inside an image's description), anchors, footnotes, @@ embeds, content: files and server routes (/static/…, /assets/…, /api/…) are left alone.
  • Decks. A deck exported content-faithful gets the appendix after its slides. A pixel-faithful deck is printed as the slides look and is not offered the option.
  • What the reader sees. Each followed link gains "(Appendix n)", and an Appendix: linked documents list precedes the appended chapters.
  • How deep it goes. The depth works like include children: 1 (the default) follows the export's own links, 2 also follows the links in those appendices, and so on.
  • Cycles. Each document is appended once, and the exported document and its included children are never appended again.
  • Access. Every linked document is read as you. A link you cannot follow, because it is denied, missing or unreadable, is marked (linked document not available) where it stands and in the list. Its title is never printed, and denied is never told apart from missing, because that would itself disclose that the document exists.
• 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.
• Charts and diagrams. Inline SVG prints in PDF, whether it is written as a block on its own lines or as one line inside a paragraph (the one-line form printed as an empty frame until MeshWeaver.Plugins#3707). Word has no HTML engine, so in DOCX an inline SVG keeps only its text labels. An image REFERENCED by link (![chart](…), SVG or raster) prints as its alt text in both formats, because the print document admits only images already inlined into it.
• 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.