Auto-convert links between spec MD files to be internal links

[swcurran]

In "normal" Markdown, when you create a link across different MD files, you reference the file and the internal link within the file, such as: [link to another spec file](other_spec.md#header-in-that-other-file). However, since spec-up merges the files together. Would it be possible to automatically convert the link in the generated spec to remove the file reference? E.g. convert the example above to [link to another spec file](#header-in-that-other-file).

I can see that there would be limits on that -- e.g. rules for when/when not to do the conversion for any given link. I would think a relative reference (no leading "/" on the file name, or perhaps no "/" at all in the file name segment).

[henkvancann]

Indeed, Spec-Up(-T) merges multiple Markdown files into one index.html, so intra-document links like [link](other_spec.md#section) will not function as expected because other_spec.md no longer exists in the final output. The correct behavior would be [link](#section).

Recommendation

It might be a good idea to implement a preprocessing step in the Spec-Up(-T) build process that:

1. Scans for links in the format [text](filename.md#header) or [text](./filename.md#header).
2. Checks if the target file is one of the markdown files merged into the spec (from specs.json > markdown_paths).
3. If so, rewrites the link to omit the file name, preserving only the hash (#header), as in [text](#header).

It might be another good thing to do to add this to the health-check of Spec-Up-T.

This work:

• Cleans up the final output
• Prevents broken links

Additional Rule (as @swcurran suggested)

Only do this if the filename has no leading / (i.e., it's a relative path).

Implementation

This transformation could be done during the Markdown-to-HTML rendering or as a preprocessing step when merging files.

[kordwarshuis]

I think the first thing we have to test is how the markdown-it library (used by Spec-Up and Spec-Up-T) handles these links. If this library is aware of the concatenation of markdown files into one HTML file, then we should use that.

• https://github.com/markdown-it/markdown-it
• https://markdown-it.github.io/