Link passes
Assembly rewrites links to files in the passes below. They run on each shard in table order, and the intra-guide pass runs once more on the stitched body. They aren’t compile hooks, so compile.hooks doesn’t turn them off. Every later pass leaves alone a link that codeEvidence rebased or that the cross-guide or publish-relative pass rewrote, and that includes the run on the stitched body. Assembly marks each of those targets, and it removes the marks after that run. So a cross-guide target such as glossary.md#term stays as the cross-guide pass wrote it, even when the guide stitches a shard named glossary.md.
Assembly marks the paths codeEvidence rebased once every hook has run, so no hook sees a mark. It finds each of those links by the text the hook wrote and its place among the links with that text. That text leaves out the links and images in the label. So a link the shard wrote with the same text, which the hook left as written, doesn’t get a mark. When a hook listed after codeEvidence changes that text, or adds or removes a link with that text above it, the publish-relative pass can rebase the hook’s path again, and leave another link with that text as it is.
The passes leave a link in fenced code or in a code span as written, and so do codeEvidence and broken-link marking. They find code with the fence scan. Since the scan pairs code spans within each line, a code span that wraps onto the next line doesn’t hide a link. Fence scan limits says when the per-shard passes and broken-link marking can disagree about a shard.
| Pass | When | Matches | Output |
|---|---|---|---|
| Cross-guide | Per shard, after the hooks | ./ and ../ paths to a shard in the guide link index |
#slug, or another output’s path plus #slug |
| Intra-guide | Per shard, then again on the stitched body | Bare and ./ paths to a shard the guide stitches, and after stitch the ../ paths no earlier pass rewrote |
#slug |
| Publish-relative | Per shard, after intra-guide | ../ paths to a file or directory that exists, or to an output of the run |
The path relative to the guide’s link base |
A pass reads a label as CommonMark reads link text, so the label can contain balanced brackets or an image, and a bracket after a backslash is text. A label can’t contain a link, so in [a [b](c) d](e) only [b](c) is a link and the outer brackets are text. The alt of an image can contain a link. A target runs from the ( right after the ] to the first ) on the same line, so a title or angle brackets stay part of it. In [](./page.md), the passes read the image and the link around it as two links. Each pass reads the outer target as it reads the target of any link, and the src as it reads the src of any image. The publish-relative pass rebases ../img/logo.png, and no pass changes a src such as ./img/logo.png. The manifest walk reads a label and a target the same way, so it follows the outer target of a linked image to a shard.
A link with a #fragment keeps it in place of the slug. Cross-guide resolution says when a cross-guide link stays in the document and which output it names otherwise. Publish-relative matching says which ../ targets the publish-relative pass skips, and ignoreGuides interaction covers a cross-guide link that keeps its shard path. The publish-relative shard also defines the link base.