The project report offers sections for paragraphs, rules, diagrams and appendices, but the markdown documents that live in the project itself cannot be part of it. Written material kept alongside the model - introductions, scope notes, decision records, hand-off documentation - has to be pasted into a paragraph or distributed separately, and it drifts out of date the moment the document is edited.

There is no way to say which documents belong in the report either. A project accumulates markdown that is deliberately not documentation: generated changelogs, readme files and the report's own markdown output. Including everything found in the project would be worse than including nothing.

SOLUTION

The report now has a 'Markdown Documents' section, switched on with the other report sections under Environment / Reporting.

Which documents take part is decided per file, in the project tree: right-click a markdown file and choose 'Include in Report' (or 'Exclude from Report' to take it out again). This is the same choice a diagram already offers for its repository - a diagram is connected to its repository, a document is connected to the report - so it is the familiar entry on the same menu, and it works on a multiple selection.

An included document is recognisable at a glance: its icon in the project tree becomes a printer. Documents that are left out keep the plain text icon, so generated changelogs and readme files stay out of the report unless they are deliberately added.

A document titles itself. Nothing is inserted above it: its own headings are used as written, the top one becoming the section heading, so the document reads in the report exactly as it reads on its own.

Documents appear in the order they are arranged in the project tree, so the order is under the author's control - moving a file up or down in the project moves it in the report.

Documents are read in whatever encoding they were written in - UTF-8 with or without a byte order mark, UTF-16, or ANSI - so accented letters, quotes and dashes arrive in the report intact.

Images referenced by a document are resolved relative to that document, and are embedded in the report when the report is generated as a standalone HTML file.

Existing projects are unaffected: no document takes part until it is explicitly included.