Doc tools: easy hyperlinking

[bzm3r]

Project description

Link notation processor

Hyperlinks between related concepts are crucial in making documentation navigable and readable. They ought to be heavily used, especially for documents meant to be viewed in a modern browser.

Markdown does not have good syntax for the creation of link anchors (typically one must use HTML directly to create link anchors).

Wikis tend to have advanced notation for creation of anchors and hyperlinks. It would be nice if we had a markdown processor that would allow us to use Wiki-style links, and was entirely under our control.

This need not be a true markdown processor either.

In its first instantiation, this tool should just be something that a human writer could manually invoke on a set of files they have just worked on, and trust that the tool will properly process links written in Wiki-notation "in-place" (so very much like a "find-and-replace" operation). (The tool should not operate if there is no git repo initiated, and if there is dirty history.)

Reference generator

Given a group of input pages, it would be nice if the documentation writer could:

• mark the "anchor" of a concept
• let the tool search for possible references
• select out of this list, and hit "ENTER" to insert references at the selected location.

To present a list of possible references, the tool could use simplistic heuristics to find locations that ought to contain a link. Some simple heuristics:

• look for matches (case insensitive) of the anchor term as reference candidates.
  • slightly more advanced (and probably unnecessary): use fuzzy matching.
• check if a match is the first below a header; if yes, increase its reference candidacy score
  • slightly more advanced (and probably unnecessary): reduce reference candidacy score based on closeness to "known" references

Steps

• Come up with a subset of Wiki-based link notation
• Implement proof-of-concept "in-place" link processor CLI tool.
• Implement a simple "find first match under section" reference selector (no need to have it do anything more than present a set of references, initially.)