A

Links And Routes

CodeAlmanac uses normal Markdown links for page-to-page navigation. A link such as [Page identity](../../architecture/wiki/page-identity) is parsed from the Markdown body and resolved to a page slug; double-bracket links are not part of the current page format [@wiki_links] [@links_manual]. File evidence belongs in sources:, not in Markdown links.

Routes come from paths under almanac/. An ordinary Markdown file drops its .md suffix, while a README.md maps to its folder route; the root README.md maps to README [@wiki_paths]. The route contract is explained in Page identity, and this page defines how authored Markdown links resolve against that route space.

Page Routes#

A link target can only ever resolve to a route that the page iterator actually indexes. Page identity owns the full derivation table; the one fact link resolution depends on is that the iterator skips Markdown files beneath the reserved manual and jobs source directories before those files get a slug, so links can never resolve into them [@wiki_paths]. Current runtime state still belongs under ~/.codealmanac/, not in almanac/jobs [@live_agreement].

The parser reads CommonMark inline links from the page body and resolves eligible hrefs to page slugs [@wiki_links]. Relative links are resolved against the source page's route. For a normal page, the base is the page's parent folder; for a folder landing page, the base is the folder route itself [@wiki_links].

Examples show the rule. From architecture/indexing, wiki-tree resolves to architecture/wiki-tree, and ../decisions/local-first-python resolves to decisions/local-first-python [@wiki_links] [@wiki_parsing_tests]. From the folder landing page architecture, wiki-tree resolves to architecture/wiki-tree [@wiki_parsing_tests].

Ignored Hrefs#

Not every Markdown link is a page link. The resolver ignores empty hrefs, anchors, slash-rooted paths, backslash paths, external URLs, links with a query string, paths with spaces, and hrefs that look like file paths because their final path segment contains a dot [@wiki_links]. Tests assert that /architecture/viewer, https://example.com, #section, and src/auth/session.py do not become page links [@wiki_parsing_tests].

This keeps navigation separate from evidence. A source file path should be recorded as a type: file source in Frontmatter and sources, not as an inline page link.

Loaded page documents store sorted, deduplicated outgoing page links [@wiki_documents]. The health graph view reports a broken Markdown page link when a stored page_links target does not match any indexed page slug [@health_graph]. Cross-wiki link rows have a separate table and health category, but current Markdown link extraction records local page links only [@wiki_documents].

The links manual says to link only real targets, or pages being created in the same run [@links_manual]. When a build or Garden run has a page plan, use it as local planning context rather than finished article content, then verify with Verify a wiki change when a wiki update needs checking.