inlineInserts

Specification for the inlineInserts compile hook. The Spec-to-test map names the tests behind this spec.

inlineInserts purpose

Guides link to captioned insert shards (.md files) in typed libraries under the docs root. Shard bodies may be markdown tables, prose, or media embeds (images, video, audio). At compile time, the hook:

1. Inlines insert markdown at the first link (per guide, per file)
2. Adds a numbered #### heading (GFM only — no HTML, no directives)
3. Rewrites later links to the same file as markdown back-links ([label](#slug))

inlineInserts layout

One library directory per insert type (library-science convention):

docs/
  diagrams/              # flow charts, sequence diagrams (markdown tables or images)
  tables/                # reference tables, comparison matrices
  figures/               # screenshots, static diagrams
  media/                 # video, audio, and other captioned media embeds
  inserts/               # optional generic captioned blocks
  review/
    insert-catalog.md    # links to ../diagrams/…, ../tables/…, ../figures/…, ../media/…

Link targets are always .md insert shards. Put binary assets alongside the shard (or under the same library) and reference them from the shard body with ![Overview](./component-map.png) or an HTML <video> / <audio> block when your renderer supports it.

Shards link with normal markdown — no <!-- directives -->.

inlineInserts link matching

A link is an insert reference when all of the following hold:

• Inline link syntax, [label](path), with the label and target read as the link passes read them. An image, ![alt](path), isn’t an insert reference.
• Target starts with an insert library directory and a /, after an optional ./ or run of ../. The directories are diagram, diagrams, table, tables, figure, figures, media, insert and inserts, in any case. No http:// or https:// URL starts that way.
• The path after the directory doesn’t start with # or whitespace. It ends in .md in any case, with at least one character before the .md.
• An optional #fragment after the .md can’t be empty, and file lookup ignores it.

The hook reads the whole shard body, fenced code and code spans included. So it inlines an insert, or writes a back-link, for an insert link in a code example too, where the link passes leave a link as written.

inlineInserts exclusions

The hook does not transform:

• Regular shard links, such as ./intro.md or ../glossary/term.md
• Direct links to binary assets such as ../figures/architecture.png or ../figures/demo.mp4; see layout
• External URLs, even when the path contains diagrams/
• Links to missing insert files (left unchanged)
• Body text when inlineInserts is disabled via compile.hooks: { "inlineInserts": false } or an explicit hook override that omits it

inlineInserts first inline

The first reference to an insert file (document order across all shards in the guide) is replaced with:

#### {Kind} {n}. {caption}

{insert shard body — tables, prose, images, video, audio, …}

• Kind — Diagram, Table, Figure, Media, or Insert (from parent library directory)
• n — serial number for that kind in this guide (see Numbered captions below)
• caption — link label, or a humanized basename when the label is empty
• Anchor slug — GitHub-style slug of the full heading (for example Table 1. Status codes → #table-1-status-codes)

The label of a linked image, [![I](./i.png)](../diagrams/d.md), contains the image. The heading then reads #### Diagram 1. ![I](./i.png), and a back-link to it uses the slug of that text, #diagram-1-iipng.

Output uses GFM headings and back-links for captions. The hook inlines each shard body as written. The assembly passes after the hooks then treat that body as part of the shard, from link rewriting to table re-alignment. A body can contain markdown tables and ![images](…).

The heading and body replace the link, so a first reference in a table cell breaks the table, as the compile example shows. Give the first reference a paragraph of its own, ahead of any table cell that links to the insert.

In the compiled markdownlint pass of merlon check, the broken row fails MD056 (table-column-count). That pass lints only the outputs that the globs in its lint.markdownlint.compiledConfig file match, and a table broken in any other output passes the check.

inlineInserts numbered captions

Serial counters are per insert kind and per guide compile:

Kind	First inline heading example	Second inline (same kind)
diagram	#### Diagram 1. Request flow	#### Diagram 2. …
table	#### Table 1. Status codes	#### Table 2. …
figure	#### Figure 1. Component map	#### Figure 2. …
media	#### Media 1. Walkthrough	#### Media 2. …

Rules:

• Diagram and table counters are independent (Diagram 1 then Table 1 then Diagram 2 is valid)
• Counters continue across shards via shared per-guide hook state
• Each guide starts at 1 for each kind (two guides sharing one insert file each get their own Diagram 1)
• Repeat links to an already inlined file do not consume a new number (back-link only)

inlineInserts deduplication

Within one guide:

• First link to ../diagrams/flow.md → inline under numbered heading
• Later links to the same resolved file (any path spelling, with or without #fragment) → `[label](#diagram-1-…)`
• Same basename in different libraries (diagrams/overview.md vs tables/overview.md) → separate headings and anchors

inlineInserts path resolution

The hook finds each insert shard in the order Path lookup order gives for inlineInserts.

inlineInserts config

Runs by default. Optional search roots, each the parent of an insert library directory such as diagrams/:

{
  "name": "architecture-review",
  "compile": {
    "hooksConfig": {
      "inlineInserts": { "searchRoots": ["shared"] }
    }
  }
}

A link to diagrams/flow.md that no earlier root in the lookup order resolves then finds shared/diagrams/flow.md.

Opt out: "hooks": { "inlineInserts": false }. See Default compile hooks.

inlineInserts compile example

Shard input:

| Insert                                      | Summary     |
| ------------------------------------------- | ----------- |
| [Request flow](../diagrams/request-flow.md) | Client path |

See [Request flow](../diagrams/request-flow.md) again in prose.

Compiled fragment (first guide mention), with trailing spaces trimmed. The header and delimiter rows keep the shard’s widths, and the insert splits the row with the link:

| Insert                                      | Summary     |
| ------------------------------------------- | ----------- |
|

#### Diagram 1. Request flow

| Step | Actor  |
| ---- | ------ |
| 1    | Client |

 | Client path |

See [Request flow](#diagram-1-request-flow) again in prose.

Example fixture: examples/sample-guides/inserts-demo/. Its catalog gives each insert’s first reference a paragraph of its own, and its table links to each insert again. Compile turns those table links into back-links and re-aligns the table. See GitHub media reference for a format matrix (PNG, JPEG, GIF, SVG, MP4, MP3/WAV, Mermaid, tables, lists) and minimal generated sample assets under figures/ and media/.

Figure with embedded image (shard figures/component-map.md):

![Component map overview](./component-map.png)

Catalog link `[Component map](../figures/component-map.md)` compiles to a numbered #### Figure 1. … heading followed by that image markdown.

Media with embedded video (shard media/walkthrough.md):

<video src="./walkthrough.mp4" controls></video>

Catalog link `[Walkthrough](../media/walkthrough.md)` compiles to #### Media 1. Walkthrough followed by the video embed.