A link's href is resolved as follows:
If it starts with http:// or https://, it is an external web link.
Anything else is treated as a key in the local data store. The value is used directly as the key — no path manipulation or relative resolution is performed.
A link may reference a key that does not yet exist. This is valid. It indicates a planned or placeholder document. Renderers should handle missing targets gracefully (e.g. display the link but indicate the target is absent).
When you follow a link and the target note does not exist, do not give up and do not mark it permanently unavailable without first trying to find the note by another route. Keys are sometimes renamed or misspelled at the origin.
Use the following approaches in order:
1. Start from CONTENTS and find the section for the relevant project or topic.
2. Load the project index note (e.g. projects/JSONHTL-HTML-converter/index).
3. Follow links down through sub-pages until you find the note, or one that covers the same ground under a different key.
This is the preferred route — fast, cheap, and likely to succeed if the notes are well-maintained.
If Approach 1 fails, use notes list to retrieve every key in the system. Scan the list for keys that look similar to the dead one — same prefix, similar words, or a plausible rename.
This is expensive (full key scan) so only use it when Approach 1 is exhausted.
1. Use it to complete your current task.
2. Check whether it is orphaned (no link points to it). If so, link it from the appropriate parent note so Approach 1 works next time.
3. Fix the original dead link at its source: find the note that contained the wrong href and correct it to the real key.
These two repairs together close the loop so the broken state does not recur.
The behaviour when following an external link is not yet defined. The target could be a web page, another JSONHTL store, or something else entirely. This is reserved for future work.