Backlinks and knowledge graph
On 2026-08-27, all G1 open decisions were resolved and G1 (static backlinks) was accepted. The theme’s main branch implements G1, which is included in OINK 0.8.0. The local and global graphs (G2/G3) remain drafts until G1 supplies real-world evidence. Their names and configuration are not public API until acceptance.
Premise
Reverse navigation and a view of connected pages come from the link graph,
independently of [[wikilink]] syntax. Hugo already accepts ordinary Markdown
links and ref / relref, so OINK can derive a graph from content authors
already write, without another parser, Goldmark extension, or authoring syntax.
The first value is backlinks, not visualization. A static inbound-link list is useful without JavaScript and remains readable in print and Markdown, making an interactive graph an optional enhancement to an already complete list.
Goals and non-goals
Goals:
- derive one language-local link index per build;
- show deterministic inbound links on a page;
- optionally show a bounded local neighborhood;
- optionally publish a whole-site view and a machine-readable graph;
- preserve ordinary preview when an edited link is stale or incomplete.
Non-goals:
- introducing
[[wikilink]]syntax; - indexing external,
mailto:, same-page anchor, or self links; - executing JavaScript to discover links already present in content;
- turning a visualization into the only way to navigate;
- promising perfect extraction from arbitrary shortcode parameters or raw HTML.
Delivery stages
| Stage | Deliverable | Runtime | Independent value |
|---|---|---|---|
| G1 | Language-local link index and backlink list | None | Reverse navigation in HTML, Print, and Markdown |
| G2 | Local graph around the current page | Existing ECharts plus a small local runtime | Spatial view with G1 as the accessible fallback |
| G3 | Global graph page and graph data output | Same runtime | Whole-site exploration and machine-readable edges |
Each stage requires separate acceptance. G1 does not depend on G2. G2 does not require every page to load graph code.
Extraction contract
The proposed index scans source content once per language and records one edge
per source/target pair. After removing fenced code and inline code, it extracts
ordinary Markdown links and ref / relref, resolves internal pages, and
removes fragments for page identity. Self-links are excluded, and repeated
references produce only one edge.
The implementation must test at least:
- duplicate links collapse to one edge;
- fenced and inline code produce no edge;
- external, protocol-relative, mail, same-page anchor, and self links are excluded;
refandrelrefare included;- each language produces an independent graph;
- an unresolved derived edge warns or is reported by the focused checker
without making ordinary
hugo serverunusable.
Raw source scanning has known omissions: it may miss a URL in a custom
shortcode parameter or raw <a href>. These omissions must be documented
rather than hidden behind a claim of a complete semantic graph.
Backlink output
G1 renders an aside group in the right rail beside the table of contents and
taxonomy clouds, placing what points to this page beside what is on this page.
The group is expanded by default and shows the first eight entries, with the
rest behind a native disclosure so a heavily referenced page cannot occupy the
entire rail.
The site key params.ui.backlinks is a bare boolean, off by default.
A page overrides it with the prefix-free front matter key backlinks, which
a section can cascade. Entries sort by stable page path: a language-independent
order that naturally groups related paths without a second ordering authority.
The group uses ordinary links and is omitted when there are no inbound pages.
G1 silently removes derived edges that it cannot resolve. This is a documented limitation of its role as a local navigation enhancement: site-wide broken-link reports would duplicate existing warnings.
Print and Markdown retain the readable list. RSS omits the list unless feed-level research shows that backlinks improve article feeds without adding unnecessary site navigation.
Interactive graph boundary
G2 uses the locally vendored ECharts graph series, with the current page at the center and its direct inbound and outbound neighbors forming the default depth. A hard node limit prevents unreadable or expensive views. Keyboard focus, text alternatives, reduced motion, forced colors, narrow screens, and print are acceptance requirements rather than later polish.
If JavaScript or ECharts is unavailable, G1 remains complete and visible. Only pages that render a graph load the runtime. The runtime must use the existing feature-bundle key to prevent asset-cache collisions between pages with different features.
Global output
G3 may add a dedicated graph page and an opt-in JSON output. The proposed JSON schema contains a version, language, nodes, and directed edges with stable URLs. It would not expose local file paths or unpublished pages. Generate this output from the same index as G1 and G2 so all three representations remain consistent.
Compatibility and migration
Ordinary Markdown remains unchanged and needs no content migration. Configuration names remain undecided until a prototype proves the minimum required surface. Every interactive or global output is off by default. A static backlink list may be considered separately because it supports local navigation without network access or browser state.
Acceptance criteria
Acceptance requires a focused graph checker, extraction fixtures, and HTML/Print/Markdown goldens. It also requires strict-build negative cases, browser accessibility and responsive tests, and a real bilingual-site build. Measure performance on a representative large site.
Open decisions
All G1 questions are resolved (see the decision log). G2/G3 must resolve these remaining questions:
- Does the local graph expose one depth or a tightly capped second depth?
- Which page metadata, if any, is useful enough to enter graph JSON?
- Is G3 useful enough to justify a new output format before G1 and G2 have production evidence?
Decision log
- 2026-08-19: Drafted the three-stage design.
- 2026-08-27: Resolved and accepted G1, scheduled for OINK 0.8.0. G1 is opt-in:
the site key
params.ui.backlinksis a bare boolean, off by default, and pages override it withbacklinks. Shell types do not restrict this policy because it belongs to the site and page. A single stable-page-path sort replaces the section → weight → title chain: one deterministic authority is enough for reverse navigation, while a multi-level sort would introduce a second navigation authority. Unresolvable edges are silently removed, without warnings, as a documented limitation. G2/G3 and graph data output still require production evidence. - 2026-08-27: Design review moved the block from the page end to the right rail. Backlinks are page metadata and belong beside the table of contents, while the page end is the reader’s completion zone: share, feedback, provenance, pager, and comments. The rail group limits visible entries to eight, with the rest behind a native disclosure.