Source tags and default banner

Compiled outputs from Merlon Docs stitch together multiple markdown shards into a single document. To help human readers and AI agents trace the compiled text back to its source, Merlon Docs includes two features by default:

1. Default Banner: A warning banner prepended to compiled files.
2. Source Tags: HTML comments wrapping each shard’s content, indicating its relative path.

Default Banner

By default, Merlon Docs prepends the following banner and a blank line to compiled outputs:

<!-- AUTO-GENERATED by Merlon Docs — edit shards, then run: merlon compile -->

This helps prevent accidental edits to generated files, directing contributors to the source shards instead.

• Global Config: Override the banner text using the banner field in merlon.config.json.
• Per-Guide Config: Disable the banner for a specific guide by setting compile.includeBanner: false in its configuration. (Defaults to true for all outputs).
• Trailing newline: compile writes the banner right before the output’s first line. The default ends with a blank line. When a custom banner lacks a trailing newline, compile adds one. So the guide’s title starts a line of its own and keeps its anchor. A later heading with the same title then keeps the number that compile’s section links give it.

Source Tags

To trace sections back to their source shards, Merlon Docs wraps each stitched section in HTML comments:

<!-- merlon-shard: start guide/section.md -->

# Section

Content.

<!-- merlon-shard: end guide/section.md -->

When compile dropped lines before a shard’s body, such as its front matter, the start tag adds the shard line the body starts on: <!-- merlon-shard: start guide/section.md#L6 -->.

The path in the tag is relative to the directory of the file the tag is in, which is the guide’s link base. So the tags in a guide’s compiled guide and in its copy in the monolith each resolve from that file’s directory. AI agents reading compiled output can use that path to easily locate and edit the exact shard responsible for a specific section of text.

• Global Config: Disable source tags entirely by setting sourceTags: false in merlon.config.json.
• Per-Guide Config: Override for a specific guide by setting compile.sourceTags: false (or true) in its configuration. Useful for outputs where wrapping comments interfere with downstream tooling.