Skip to content

Add LaTeX-style clickable, auto-numbered figure references #101

Description

@jonfroehlich

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)

  1. Auto-numbering via CSS counters — increment a counter per <figure>; render figcaption::before { content: "Figure " counter(fig) ". " }. Separate counters for figures vs. videos.
  2. Authoring convention — each caption gets a stable id, e.g. {: #fig-servo-wiring }.
  3. 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.
  4. Graceful degradation — without JS the anchor still links to the figure; ensure link text is populated for screen readers (a11y).

Open questions

Tasks

  • Prototype on one lesson (e.g., advancedio/servo.md)
  • CSS counters for figures/videos
  • JS cross-ref resolver in head_custom.html
  • Accessibility check (link text populated, focus on jump)
  • Document convention in website-dev.md

Related: #69. Possible plugin-based implementation depends on #98.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestfigures-mediaFigures, captions, diagrams, images, video/embedsv2.0Targeted for the Version 2.0 release

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions