Summary
Add LaTeX/Overleaf-style figure references: writing "Figure 2" auto-numbers and becomes a clickable link that jumps to the figure. Today figures are captioned manually (**Figure.** / **Video.**) with no numbers and no cross-reference links.
Related to #69 (figure/table caption markup) — that issue is about caption tags; this is about auto-numbering + clickable cross-references.
Constraint
On the default GitHub Pages build we can't run custom Jekyll plugins, so a pure-Pages solution must be CSS counters (auto-numbering) + client-side JS (cross-ref resolution). If we adopt a GitHub Actions build (#98), a real Jekyll plugin becomes possible instead.
Proposed design (Pages-compatible)
- Auto-numbering via CSS counters — increment a counter per
<figure>; render figcaption::before { content: "Figure " counter(fig) ". " }. Separate counters for figures vs. videos.
- Authoring convention — each caption gets a stable id, e.g.
{: #fig-servo-wiring }.
- Cross-references — author writes
<a class="figref" href="#fig-servo-wiring"></a>; a small JS (loaded via head_custom.html) builds an id→number map from rendered numbers, fills in each .figref link text ("Figure 2"), and smooth-scrolls on click.
- Graceful degradation — without JS the anchor still links to the figure; ensure link text is populated for screen readers (a11y).
Open questions
Tasks
Related: #69. Possible plugin-based implementation depends on #98.
Summary
Add LaTeX/Overleaf-style figure references: writing "Figure 2" auto-numbers and becomes a clickable link that jumps to the figure. Today figures are captioned manually (
**Figure.**/**Video.**) with no numbers and no cross-reference links.Related to #69 (figure/table caption markup) — that issue is about caption tags; this is about auto-numbering + clickable cross-references.
Constraint
On the default GitHub Pages build we can't run custom Jekyll plugins, so a pure-Pages solution must be CSS counters (auto-numbering) + client-side JS (cross-ref resolution). If we adopt a GitHub Actions build (#98), a real Jekyll plugin becomes possible instead.
Proposed design (Pages-compatible)
<figure>; renderfigcaption::before { content: "Figure " counter(fig) ". " }. Separate counters for figures vs. videos.{: #fig-servo-wiring }.<a class="figref" href="#fig-servo-wiring"></a>; a small JS (loaded viahead_custom.html) builds an id→number map from rendered numbers, fills in each.figreflink text ("Figure 2"), and smooth-scrolls on click.Open questions
<a>vs. a kramdown/Liquid snippet.Tasks
advancedio/servo.md)head_custom.htmlwebsite-dev.mdRelated: #69. Possible plugin-based implementation depends on #98.