feat: make markdown footnotes navigable

Markdown footnotes were rendered by maud as bare paragraphs with no
anchors, and markers had no href, so they were not navigable. Render the
footnote definitions ourselves into an anchored <section><ol> with
back-links (bypassing maud's bare append by clearing the document's
footnotes before rendering the body), and make the default footnote
component a clickable link to the definition.

The footnote <section><ol> markup is now shared between the markdown and
djot renderers via a new internal footnote module, so both formats produce
the same structure. The djot marker is routed back through the (now
clickable) footnote component.

Author: veeso

examples/simple_blog/blog/getting-started/index.md

@@ -43,4 +43,16 @@ A post directory contains:
 
 Run `gleam run` to build your site. The generated HTML, feeds, and sitemap will be written to the output directory.
 
+## Footnotes
+
+Blogatto supports footnotes in Markdown posts[^obsidian]. References are
+rendered as clickable links to the definitions at the bottom of the post[^nav],
+and each definition links back to where it was referenced[^backref].
+
 Happy blogging!
+
+[^obsidian]: Footnotes use the Obsidian syntax: `[^label]` for the reference and `[^label]: ...` for the definition.
+
+[^nav]: Click a footnote number to jump to its definition.
+
+[^backref]: Use the back-link to return to the reference.

src/blogatto/config/post.gleam

@@ -21,9 +21,12 @@
 
 import blogatto/config/post/code
 import blogatto/post.{type Post, type PostMetadata}
+import gleam/int
 import gleam/list
 import gleam/option.{type Option, None}
+import lustre/attribute
 import lustre/element.{type Element}
+import lustre/element/html
 import maud/components as maud_components
 
 /// Configuration for discovering and rendering blog posts.
@@ -179,7 +182,23 @@ pub fn default_options() -> Options {
 /// Return the default components, rendering each markdown element as its
 /// corresponding HTML element without additional attributes or styling.
 pub fn default_components() -> Components(msg) {
-  from_maud_components(maud_components.default())
+  Components(
+    ..from_maud_components(maud_components.default()),
+    footnote: default_footnote,
+  )
+}
+
+/// Default footnote reference marker: a superscript link to the footnote
+/// definition (`#fn-N`), anchored (`id="fnref-N"`) so the definition can link
+/// back. `number` is the footnote number; `children` is the marker text.
+fn default_footnote(number: Int, children: List(Element(msg))) -> Element(msg) {
+  let num = int.to_string(number)
+  html.sup([], [
+    html.a(
+      [attribute.id("fnref-" <> num), attribute.href("#fn-" <> num)],
+      children,
+    ),
+  ])
 }
 
 /// Set the `Components` used for rendering posts.

src/blogatto/internal/builder/post/djot.gleam

@@ -5,6 +5,7 @@
 //// approach so other source formats can be added as sibling submodules.
 
 import blogatto/config/post.{type Components, type PostConfig}
+import blogatto/internal/builder/post/footnote
 import frontmatter as fm_extractor
 import gleam/dict.{type Dict}
 import gleam/int
@@ -63,47 +64,14 @@ fn render_footnotes(
   footnotes: Dict(String, List(jot.Container)),
   ctx: Context(msg),
 ) -> List(Element(msg)) {
-  let items =
-    ordered_refs
-    |> list.filter_map(fn(reference) {
-      use containers <- result.map(dict.get(footnotes, reference))
-      let number =
-        ctx.footnote_numbers |> dict.get(reference) |> result.unwrap(0)
-      render_footnote_item(number, containers, ctx)
-    })
-  case items {
-    [] -> []
-    _ -> [
-      element.element("section", [attribute.class("footnotes")], [
-        element.element("ol", [], items),
-      ]),
-    ]
-  }
-}
-
-/// Render a single footnote definition as an `<li id="fn-N">` containing the
-/// definition body followed by a back-link to its reference site.
-fn render_footnote_item(
-  number: Int,
-  containers: List(jot.Container),
-  ctx: Context(msg),
-) -> Element(msg) {
-  let num = int.to_string(number)
-  let body = list.map(containers, render_container(_, ctx, jot.Loose))
-  let backlink =
-    element.element(
-      "a",
-      [
-        attribute.href("#fnref-" <> num),
-        attribute.class("footnote-backref"),
-      ],
-      [element.text("↩")],
-    )
-  element.element(
-    "li",
-    [attribute.id("fn-" <> num)],
-    list.append(body, [backlink]),
-  )
+  ordered_refs
+  |> list.filter_map(fn(reference) {
+    use containers <- result.map(dict.get(footnotes, reference))
+    let number = ctx.footnote_numbers |> dict.get(reference) |> result.unwrap(0)
+    let body = list.map(containers, render_container(_, ctx, jot.Loose))
+    footnote.item(number, body)
+  })
+  |> footnote.section
 }
 
 /// Assign a footnote number to each reference in order of first appearance.
@@ -316,18 +284,10 @@ fn render_inline(inline: jot.Inline, ctx: Context(msg)) -> Element(msg) {
         ctx.footnote_numbers
         |> dict.get(reference)
         |> result.unwrap(0)
-      let num = int.to_string(number)
-      // Render the marker directly: it must carry both an `id` (the back-link
-      // target) and an `href` to the definition, which the `footnote`
-      // component (number + children only) cannot express. The visible text is
-      // the number, not the raw reference key (jot keeps its leading `^`).
-      element.element("sup", [], [
-        element.element(
-          "a",
-          [attribute.id("fnref-" <> num), attribute.href("#fn-" <> num)],
-          [element.text(num)],
-        ),
-      ])
+      // The visible marker text is the number, not the raw reference key (jot
+      // keeps its leading `^`). The default `footnote` component renders it as
+      // a link to the definition.
+      ctx.components.footnote(number, [element.text(int.to_string(number))])
     }
     jot.Code(content: text) -> ctx.components.code(None, [element.text(text)])
     jot.MathInline(content: latex) ->

src/blogatto/internal/builder/post/footnote.gleam

@@ -0,0 +1,43 @@
+//// Shared footnote markup helpers for the post renderers.
+////
+//// Both the markdown and djot renderers emit the footnote definitions as a
+//// `<section class="footnotes"><ol>` of anchored `<li id="fn-N">` items, each
+//// ending with a back-link to its reference site. Keeping the markup here
+//// guarantees both source formats produce the same structure.
+
+import gleam/int
+import gleam/list
+import lustre/attribute
+import lustre/element.{type Element}
+
+/// Wrap the rendered footnote definition `items` in a `<section><ol>`. Returns
+/// an empty list when there are no footnotes, so callers can append it
+/// unconditionally.
+pub fn section(items: List(Element(msg))) -> List(Element(msg)) {
+  case items {
+    [] -> []
+    _ -> [
+      element.element("section", [attribute.class("footnotes")], [
+        element.element("ol", [], items),
+      ]),
+    ]
+  }
+}
+
+/// Render a single footnote definition as an `<li id="fn-N">` containing the
+/// already-rendered definition `body` followed by a back-link to its reference
+/// site (`#fnref-N`).
+pub fn item(number: Int, body: List(Element(msg))) -> Element(msg) {
+  let num = int.to_string(number)
+  let backlink =
+    element.element(
+      "a",
+      [attribute.href("#fnref-" <> num), attribute.class("footnote-backref")],
+      [element.text("↩")],
+    )
+  element.element(
+    "li",
+    [attribute.id("fn-" <> num)],
+    list.append(body, [backlink]),
+  )
+}

src/blogatto/internal/builder/post/markdown.gleam

@@ -10,24 +10,66 @@
 
 import blogatto/config/post.{type PostConfig}
 import blogatto/config/post/code
+import blogatto/internal/builder/post/footnote
+import gleam/dict
+import gleam/int
 import gleam/list
 import gleam/option.{type Option}
 import gleam/string
 import lustre/element.{type Element}
 import maud
 import maud/components as maud_components
+import mork
 import mork/document as mork_document
 
 /// File extension recognized by the markdown source format.
 pub const extension: String = "md"
 
 /// Render markdown `content` to Lustre elements using the post configuration.
+///
+/// The document body is rendered first, then the footnote definitions are
+/// rendered separately into an anchored `<section><ol>` (with back-links) so
+/// footnotes are navigable, matching the djot renderer. maud's own footnote
+/// append (bare paragraphs, no anchors) is bypassed by clearing the
+/// document's footnotes before rendering the body.
 pub fn render(config: PostConfig(msg), content: String) -> List(Element(msg)) {
-  maud.render_markdown(
-    content,
-    mork_options(config.options),
-    to_maud_components(config),
-  )
+  let components = to_maud_components(config)
+  let document =
+    mork.parse_with_options(
+      options: mork_options(config.options),
+      input: content,
+    )
+  let body =
+    maud.render_document(
+      mork_document.Document(..document, footnotes: dict.new()),
+      components,
+    )
+  list.append(body, render_footnotes(document, components))
+}
+
+/// Render the markdown footnote definitions into an anchored `<section><ol>`,
+/// ordered by footnote number. Each definition's blocks are rendered through
+/// maud so they share the configured components.
+fn render_footnotes(
+  document: mork_document.Document,
+  components: maud_components.Components(msg),
+) -> List(Element(msg)) {
+  document.footnotes
+  |> dict.values
+  |> list.sort(fn(a, b) { int.compare(a.num, b.num) })
+  |> list.map(fn(data) {
+    let body =
+      maud.render_document(
+        mork_document.Document(
+          ..document,
+          blocks: data.blocks,
+          footnotes: dict.new(),
+        ),
+        components,
+      )
+    footnote.item(data.num, body)
+  })
+  |> footnote.section
 }
 
 /// Convert blogatto `Components` to maud `Components`, wrapping the `code`

test/blogatto/builder/post/markdown_test.gleam

@@ -0,0 +1,51 @@
+import blogatto/config/post as post_cfg
+import blogatto/internal/builder/post/markdown
+import gleam/string
+import gleeunit/should
+import lustre/element
+
+fn render(content: String) -> String {
+  let config = post_cfg.default()
+  markdown.render(config, content)
+  |> element.fragment
+  |> element.to_string
+}
+
+// --- footnotes ---
+
+pub fn footnote_definition_content_is_rendered_test() {
+  let html = render("Body[^a].\n\n[^a]: A footnote.\n")
+  html |> string.contains("A footnote.") |> should.be_true
+}
+
+pub fn footnote_marker_shows_number_test() {
+  let html = render("Body[^note].\n\n[^note]: A footnote.\n")
+  html |> string.contains(">1</a>") |> should.be_true
+}
+
+pub fn footnote_marker_links_to_definition_test() {
+  let html = render("Body[^a].\n\n[^a]: A footnote.\n")
+  // Marker is a clickable link to the definition.
+  html |> string.contains("href=\"#fn-1\"") |> should.be_true
+  // Definition is anchored so the marker can jump to it.
+  html |> string.contains("id=\"fn-1\"") |> should.be_true
+  // Definition links back to the marker.
+  html |> string.contains("href=\"#fnref-1\"") |> should.be_true
+  html |> string.contains("id=\"fnref-1\"") |> should.be_true
+}
+
+pub fn footnotes_numbered_sequentially_test() {
+  let html = render("One[^a] two[^b].\n\n[^a]: Alpha.\n\n[^b]: Bravo.\n")
+  let assert Ok(one_index) = string.split_once(html, ">1</a>")
+  let assert Ok(two_index) = string.split_once(html, ">2</a>")
+  // Marker "1" must appear before marker "2" in document order.
+  { string.length(one_index.0) < string.length(two_index.0) }
+  |> should.be_true
+}
+
+pub fn footnote_definition_links_back_to_correct_marker_test() {
+  let html = render("One[^a] two[^b].\n\n[^a]: Alpha.\n\n[^b]: Bravo.\n")
+  // Definition 1 is anchored as fn-1 and holds the first footnote body.
+  let assert Ok(#(_, after_fn1)) = string.split_once(html, "id=\"fn-1\"")
+  after_fn1 |> string.contains("Alpha.") |> should.be_true
+}