datalog-theme 0.7.0 → 0.9.0

data/_plugins/licenses.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Datalog
+  # The licence of a page's text and figures, and of its code samples, for
+  # the reuse notice, the JSON-LD and the head's rel="license" link:
+  #
+  #   content_license: CC-BY-4.0     # _config.yml: the default for every article
+  #
+  #   license: CC-BY-SA-4.0          # front matter: this page's own
+  #   license: false                 # front matter: none for this page
+  #   license:                       # front matter: a licence the theme does not know
+  #     name: Open Government Licence v3.0
+  #     url: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
+  #     holder: The Lab
+  #     year: 2026
+  #   code_license: MIT              # the code samples, when their licence differs
+  #
+  # The repository's LICENSE covers the theme's software; these settings are
+  # for what a site publishes. Datasets and packages carry their own
+  # `license` and never take the site's default.
+  module Licenses
+    module_function
+
+    # SPDX identifiers, with the name readers see and the licence text.
+    KNOWN = {
+      "CC-BY-4.0" => ["CC BY 4.0", "https://creativecommons.org/licenses/by/4.0/"],
+      "CC-BY-SA-4.0" => ["CC BY-SA 4.0", "https://creativecommons.org/licenses/by-sa/4.0/"],
+      "CC-BY-ND-4.0" => ["CC BY-ND 4.0", "https://creativecommons.org/licenses/by-nd/4.0/"],
+      "CC-BY-NC-4.0" => ["CC BY-NC 4.0", "https://creativecommons.org/licenses/by-nc/4.0/"],
+      "CC-BY-NC-SA-4.0" => ["CC BY-NC-SA 4.0", "https://creativecommons.org/licenses/by-nc-sa/4.0/"],
+      "CC-BY-NC-ND-4.0" => ["CC BY-NC-ND 4.0", "https://creativecommons.org/licenses/by-nc-nd/4.0/"],
+      "CC0-1.0" => ["CC0 1.0", "https://creativecommons.org/publicdomain/zero/1.0/"],
+      "MIT" => ["MIT", "https://spdx.org/licenses/MIT.html"],
+      "Apache-2.0" => ["Apache 2.0", "https://spdx.org/licenses/Apache-2.0.html"],
+      "BSD-2-Clause" => ["BSD 2-Clause", "https://spdx.org/licenses/BSD-2-Clause.html"],
+      "BSD-3-Clause" => ["BSD 3-Clause", "https://spdx.org/licenses/BSD-3-Clause.html"],
+      "GPL-3.0-only" => ["GPL 3.0", "https://spdx.org/licenses/GPL-3.0-only.html"],
+      "GPL-3.0-or-later" => ["GPL 3.0 or later", "https://spdx.org/licenses/GPL-3.0-or-later.html"],
+      "LGPL-3.0-only" => ["LGPL 3.0", "https://spdx.org/licenses/LGPL-3.0-only.html"],
+      "AGPL-3.0-only" => ["AGPL 3.0", "https://spdx.org/licenses/AGPL-3.0-only.html"],
+      "MPL-2.0" => ["MPL 2.0", "https://spdx.org/licenses/MPL-2.0.html"],
+      "ISC" => ["ISC", "https://spdx.org/licenses/ISC.html"],
+      "Unlicense" => ["The Unlicense", "https://spdx.org/licenses/Unlicense.html"],
+      "all-rights-reserved" => ["All rights reserved", nil]
+    }.freeze
+
+    # Other spellings: "CC BY" and "cc0" take the current version; the GPL
+    # family without a suffix means "only", as SPDX reads it.
+    ALIASES = {
+      "CC-BY" => "CC-BY-4.0", "CC-BY-SA" => "CC-BY-SA-4.0", "CC-BY-ND" => "CC-BY-ND-4.0",
+      "CC-BY-NC" => "CC-BY-NC-4.0", "CC-BY-NC-SA" => "CC-BY-NC-SA-4.0", "CC-BY-NC-ND" => "CC-BY-NC-ND-4.0",
+      "CC0" => "CC0-1.0", "GPL-3.0" => "GPL-3.0-only", "LGPL-3.0" => "LGPL-3.0-only", "AGPL-3.0" => "AGPL-3.0-only"
+    }.freeze
+
+    # Collections whose pages carry their own licence and never the site's.
+    OWN_LICENSE = %w[datasets packages].freeze
+
+    def key(value)
+      value.to_s.strip.upcase.gsub(/[\s_]+/, "-")
+    end
+
+    LOOKUP = KNOWN.keys.to_h { |id| [key(id), id] }.merge(ALIASES.to_h { |from, to| [key(from), to] }).freeze
+
+    # The licence of the page's text and figures, or nil.
+    def content(page, site)
+      resolve(setting(page, "license", site, "content_license"), page, site)
+    end
+
+    # The licence of the page's code samples, or nil.
+    def code(page, site)
+      resolve(setting(page, "code_license", site, "code_license"), page, site)
+    end
+
+    # The page's own value, else the site's; `false` declines the site's.
+    def setting(page, page_key, site, site_key)
+      value = Authors.value(page, page_key)
+      return value unless value.nil?
+      return if OWN_LICENSE.include?(Authors.value(page, "collection").to_s)
+
+      Authors.value(site, site_key)
+    end
+
+    def resolve(value, page, site)
+      return if value.nil? || value == false || (value.is_a?(String) && value.strip.empty?)
+
+      given = value.is_a?(Hash) ? Authors.present(value) : { "name" => value.to_s.strip }
+      id = LOOKUP[key(given["id"] || given["name"])]
+      name, url = KNOWN[id] if id
+      # A name that is not itself an identifier is the label the page chose.
+      name = given["name"] if given["name"] && LOOKUP[key(given["name"])].nil?
+      licence = { "id" => id, "name" => name, "url" => given["url"] || url, "reserved" => id == "all-rights-reserved" }
+      licence.merge(holder(given, page, site)).compact
+    end
+
+    # The copyright holder and year: the page's, else the site default's,
+    # else the page's authors and its date.
+    def holder(given, page, site)
+      site_given = Authors.value(site, "content_license")
+      site_given = site_given.is_a?(Hash) ? Authors.present(site_given) : {}
+      names = Array(given["holder"] || site_given["holder"]).map(&:to_s).reject(&:empty?)
+      authors = Authors.authors(page, site).map { |author| author["name"] }
+      people = names.empty? || (names - authors).empty?
+      names = authors if names.empty?
+      year = year(given["year"] || site_given["year"] || Authors.value(page, "date"))
+      { "holders" => names, "holder" => (names.join(", ") unless names.empty?), "people" => people, "year" => year }
+    end
+
+    # A year, a date or a string naming either.
+    def year(value)
+      return value if value.is_a?(Integer)
+      return value.year if value.respond_to?(:year)
+
+      text = value.to_s.strip
+      return text.to_i if text.match?(/\A\d{4}\z/)
+
+      Time.parse(text).year unless text.empty?
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  module LicenseFilters
+    def page_license(page)
+      Licenses.content(page, @context["site"])
+    end
+
+    def page_code_license(page)
+      Licenses.code(page, @context["site"])
+    end
+  end
+end
+
+Liquid::Template.register_filter(Datalog::LicenseFilters)

data/_plugins/math_preprocessor.rb

@@ -19,16 +19,43 @@ module MathPreprocessor
   ].freeze
 
   INLINE_PATTERNS = [
+    # Pandoc's rule for inline math, so prices and shell variables stay text:
+    # the opening $ is followed by a non-space, the closing $ follows a
+    # non-space and is not followed by a digit, and a blank line ends it.
     {
-      regex: /(?<![\\$])(?<open>\$)(?!\$)(?<body>[^$]+?)(?<close>\$)(?!\$)/m,
+      regex: /(?<![\\$])(?<open>\$)(?![\s$])(?<body>(?:[^$\\\n]|\\.|\n(?![ \t]*\n))+?)(?<![\s\\])(?<close>\$)(?![$\d])/m,
       tag: "span"
     },
+    # MathJax and KaTeX also render math with spaces inside the dollars, such
+    # as `$ \frac{a}{b} $`, which the rule above leaves out, so a page whose
+    # only math was written that way loaded no engine. Such a pair counts when
+    # its body holds a TeX command, a superscript or a subscript, which prices
+    # like `$ 5 or $ 10` do not.
+    {
+      regex: /(?<![\\$])(?<open>\$)(?!\$)(?<body>(?:[^$\\\n]|\\.|\n(?![ \t]*\n))+?)(?<!\\)(?<close>\$)(?![$\d])/m,
+      tag: "span",
+      requires: /\\[a-zA-Z]+|[\^_]/
+    },
     {
       regex: /(?<open>\\\()(?<body>.+?)(?<close>\\\))/m,
       tag: "span"
     }
   ].freeze
 
+  # Code shows dollar signs literally (shell and R variables, amounts in SQL),
+  # so fenced blocks, highlight tags, <pre>/<code> elements and inline code
+  # spans are set aside before looking for math and put back afterwards.
+  CODE_PATTERNS = [
+    /^([ \t]*)(`{3,}|~{3,})[^\n]*\n.*?(?:^\1\2[ \t]*$|\z)/m,
+    /\{%-?\s*highlight\b.*?\{%-?\s*endhighlight\s*-?%\}/m,
+    %r{<(pre|code)\b[^>]*>.*?</\1>}mi,
+    /(?<!`)(`+)(?!`)(?:(?!\n[ \t]*\n).)+?(?<!`)\1(?!`)/m
+  ].freeze
+
+  # NUL marks masked code, since page content never contains it. It is written as
+  # an escape: a raw NUL byte in the source stopped RuboCop from parsing the file.
+  PLACEHOLDER = /\x00(\d+)\x00/
+
   class Processor
     attr_reader :expressions
 
@@ -40,13 +67,24 @@ module MathPreprocessor
     def process
       return @content unless @content&.match?(/\$|\\\(|\\\[|\\begin\{/)
 
-      processed = @content.dup
+      @segments = []
+      processed = CODE_PATTERNS.reduce(@content.dup) do |text, pattern|
+        text.gsub(pattern) { |match| mask(match) }
+      end
       processed = apply_patterns(processed, DISPLAY_PATTERNS, display: true)
-      apply_patterns(processed, INLINE_PATTERNS, display: false)
+      processed = apply_patterns(processed, INLINE_PATTERNS, display: false)
+      # A segment set aside can contain the placeholder of an earlier one.
+      processed = processed.gsub(PLACEHOLDER) { @segments[Regexp.last_match(1).to_i] } while processed.match?(PLACEHOLDER)
+      processed
     end
 
     private
 
+    def mask(segment)
+      @segments << segment
+      "\x00#{@segments.size - 1}\x00"
+    end
+
     def apply_patterns(text, patterns, display: false)
       patterns.reduce(text) do |result, pattern|
         result.gsub(pattern[:regex]) do |match|
@@ -55,8 +93,11 @@ module MathPreprocessor
           close = Regexp.last_match[:close]
 
           next match if body.nil? || body.strip.empty?
+          next match if pattern[:requires] && !pattern[:requires].match?(body)
 
-          wrapper_for(match, body, open, close, pattern[:tag], display: display)
+          # Each wrapper is set aside like code. Otherwise a later pattern could
+          # pair a dollar sign inside it with one in the text that follows.
+          mask(wrapper_for(match, body, open, close, pattern[:tag], display: display))
         end
       end
     end
@@ -66,8 +107,12 @@ module MathPreprocessor
       cleaned_source = cleanup_source(latex)
       record_expression(cleaned_source, alt_text)
 
+      # ARIA forbids aria-label on an element with no role, such as a plain span.
+      # axe let it pass while the span held the raw LaTeX as text, and failed it
+      # once MathJax rendered the expression; the math role allows the label.
       attributes = {
         "class" => display ? "math-expression math-expression--source" : "math-expression-inline math-expression--source",
+        "role" => "math",
         "data-math-alt" => alt_text,
         "data-math-source" => cleaned_source,
         "aria-label" => alt_text,
@@ -165,9 +210,9 @@ module MathPreprocessor
   def apply(document)
     return unless document.respond_to?(:content)
     return unless document.respond_to?(:output_ext) && document.output_ext == ".html"
-    # A page that opts out of math rendering (`math: false` or `mathjax: false`)
-    # keeps its dollar signs and TeX-looking text verbatim.
-    return if document.respond_to?(:data) && (document.data["math"] == false || document.data["mathjax"] == false)
+    # A page that opts out of math rendering keeps its dollar signs and
+    # TeX-looking text verbatim.
+    return if document.respond_to?(:data) && math_setting(document.data) == false
 
     content = document.content
     return unless content&.match?(/\$|\\\(|\\\[|\\begin\{/)
@@ -177,6 +222,13 @@ module MathPreprocessor
     document.content = updated_content
     document.data["math_expressions"] = processor.expressions if processor.expressions.any?
   end
+
+  # `math`, or its alias `mathjax` when `math` is unset, as
+  # _includes/meta/math-config.html reads them. A `mathjax: true` in front
+  # matter defaults used to win over a page's `math: false`.
+  def math_setting(data)
+    data["math"].nil? ? data["mathjax"] : data["math"]
+  end
 end
 
 # Posts are documents, so registering them separately ran the preprocessor

data/_plugins/notebook_converter.rb

@@ -7,6 +7,7 @@ require "fileutils"
 require "cgi"
 require "loofah"
 require "base64"
+require_relative "rouge_highlight_filter"
 
 module Datalog
   module NotebookRenderer
@@ -94,14 +95,30 @@ module Datalog
                                       metadata: build_sanitization_metadata(meta, cell_index: cell_index))
       return if sanitized.to_s.strip.empty?
 
-      %(<section class="notebook-cell notebook-cell--markdown">\n#{sanitized}\n</section>)
+      %(<section class="notebook-cell notebook-cell--markdown">\n#{demote_headings(sanitized.to_s)}\n</section>)
+    end
+
+    # The notebook layout gives the page its <h1>, and a notebook's first
+    # markdown cell usually repeats the title as `# Title`. Each heading moves
+    # down a level (h1 to h2, and so on to h6), which keeps one <h1> on the
+    # page and the cells' own outline under it.
+    def demote_headings(html)
+      html.gsub(%r{<(/?)h([1-5])(?=[\s>])}i) { "<#{Regexp.last_match(1)}h#{Regexp.last_match(2).to_i + 1}" }
     end
 
     # Class names mirror the theme stylesheet (`.notebook-cell--input`,
     # `.notebook-cell__code` and `.notebook-cell__outputs` in _sass/_components.scss).
     def render_code(cell, source, metadata, site, cell_index)
       language = cell.dig("metadata", "language") || metadata[:language] || "text"
-      code_html = %(<pre class="notebook-cell__code"><code class="language-#{language}">#{CGI.escapeHTML(source)}</code></pre>)
+      # The language comes from the notebook file, so it is cut down to the
+      # characters a class name can hold before it goes into the attribute.
+      language_class = language.to_s.gsub(/[^\w+#.-]/, "")
+      # Rouge highlights the cell as the site builds, as kramdown does for code
+      # blocks, and escapes it.
+      highlighted = Jekyll::RougeHighlightFilter.highlight(source, language_class)
+      pre_attributes = %(class="highlight notebook-cell__code" tabindex="0")
+      code_attributes = %(class="language-#{language_class}")
+      code_html = %(<pre #{pre_attributes}><code #{code_attributes}>#{highlighted}</code></pre>)
       base_metadata = metadata.respond_to?(:merge) ? metadata.merge(language: language) : { language: language }
       outputs_html = render_outputs(Array(cell["outputs"]), site: site, cell_index: cell_index, metadata: base_metadata)
       outputs_html = %(\n<div class="notebook-cell__outputs">\n#{outputs_html}\n</div>) unless outputs_html.empty?
@@ -157,11 +174,13 @@ module Datalog
     def image_output_html(output)
       data = output["data"] || {}
 
+      # Jupyter writes base64 image data split over lines or ending in a newline,
+      # and the data URI check rejects whitespace, which dropped those images.
       if (png = data["image/png"])
-        html = %(<img src="data:image/png;base64,#{Array(png).join}" alt="Notebook output" />)
+        html = %(<img src="data:image/png;base64,#{Array(png).join.gsub(/\s+/, '')}" alt="Notebook output" />)
         return [html, "image/png"]
       elsif (jpeg = data["image/jpeg"])
-        html = %(<img src="data:image/jpeg;base64,#{Array(jpeg).join}" alt="Notebook output" />)
+        html = %(<img src="data:image/jpeg;base64,#{Array(jpeg).join.gsub(/\s+/, '')}" alt="Notebook output" />)
         return [html, "image/jpeg"]
       elsif (svg = data["image/svg+xml"])
         encoded = Base64.strict_encode64(Array(svg).join)

data/_plugins/plugin_loader.rb

@@ -149,7 +149,9 @@ end
 
 module Datalog
   module PluginLoaderHooks
-    HOOK_SCOPES = %i[pages documents posts].freeze
+    # Posts are documents: Jekyll fires a post's `posts` hooks and then its
+    # `documents` hooks, so registering both ran every plugin hook twice a post.
+    HOOK_SCOPES = %i[pages documents].freeze
 
     module_function
 

data/_plugins/publications_generator.rb

@@ -6,7 +6,13 @@ module Jekyll
     priority :low
 
     def generate(site)
-      publications_data = site.data["publications"] ||= {}
+      publications_data = site.data["publications"]
+      # _data/publications.yml is normally a map with `settings` and
+      # `manual_entries`; a plain list of entries is read as the manual
+      # entries rather than stopping the build with a TypeError.
+      publications_data = { "manual_entries" => publications_data } if publications_data.is_a?(Array)
+      publications_data = {} unless publications_data.is_a?(Hash)
+      site.data["publications"] = publications_data
       settings = publications_data["settings"] || {}
       config_source = site.config.dig("theme_options", "publications", "bibtex_source")
       bibtex_source = settings["bibtex_source"] || config_source
@@ -22,7 +28,7 @@ module Jekyll
         end
       end
 
-      manual_entries = publications_data["manual_entries"] || []
+      manual_entries = Array(publications_data["manual_entries"]).select { |entry| entry.is_a?(Hash) }
       combined = (imported_entries + manual_entries).map { |entry| normalize_entry(entry) }
 
       academic_citations = site.data.dig("academic", "citations", "per_publication") || {}

data/_plugins/references.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Datalog
+  # Numbered figures and tables, and references to them, within a page:
+  #
+  #   {% figure id="fig-power" src="/assets/img/power.png" alt="Power curve" %}
+  #   Power as a function of effect size $\delta$.
+  #   {% endfigure %}
+  #
+  #   {% table id="tab-runs" %}
+  #   Simulation runs by sample size.
+  #
+  #   | n | runs |
+  #   |---|------|
+  #   {% endtable %}
+  #
+  #   As {% ref fig-power %} shows, ...
+  #
+  # The tags write placeholders. Once the page's Markdown is converted, every
+  # target gets its number in the order it appears, so a reference may come
+  # before its figure, and each reference becomes a link reading "Figure 2".
+  # A duplicate id or a reference to nothing stops the build. Equations are
+  # numbered and referenced by MathJax (\label and \eqref) instead.
+  #
+  # A caption is the body of the tag, not an attribute, so math in it goes
+  # through the math preprocessor like the rest of the page.
+  #
+  # Theorems, definitions and the other statements in _plugins/statements.rb
+  # are numbered and referred to the same way.
+  module References
+    module_function
+
+    # Each kind counts separately; the label comes from _data/i18n.
+    KINDS = {
+      "figure" => "Figure", "table" => "Table",
+      "theorem" => "Theorem", "lemma" => "Lemma", "proposition" => "Proposition", "corollary" => "Corollary",
+      "definition" => "Definition", "assumption" => "Assumption", "example" => "Example", "remark" => "Remark"
+    }.freeze
+    ID = /\A[A-Za-z][\w.:-]*\z/
+    # A label given in place of the number, as in "Theorem A".
+    CUSTOM_LABEL = /\A[[:alnum:]][[:alnum:].'*-]*\z/
+    TARGET = /data-ref-target="([^"]+)" data-ref-kind="([a-z]+)"(?: data-ref-number="([^"]+)")?/
+    # A label ends with a full stop unless the tag chose another ending.
+    LABEL = %r{<span class="datalog-ref-label" data-ref-for="([^"]+)"(?: data-ref-end="([^"]*)")?></span>}
+    LINK = %r{<a class="datalog-ref" href="#([^"]+)" data-ref="\1">[^<]*</a>}
+    SOURCE_TAG = /\{%-?\s*(#{KINDS.keys.join('|')})\b([^%]*)-?%\}/
+
+    def number(document)
+      content = document.content
+      return unless content&.include?("data-ref")
+
+      targets = targets(content.scan(TARGET), document)
+      content = content.gsub(LABEL) do
+        id, ending = Regexp.last_match.captures
+        text = "#{CGI.escapeHTML(targets.fetch(id))}#{ending || '.'}"
+        %(<span class="datalog-ref-label" data-ref-for="#{id}">#{text}</span>)
+      end
+      document.content = link_references(content, targets, document)
+    end
+
+    # Jekyll runs no hooks for an excerpt, and renders it when a template first
+    # asks for it, which on a listing page can be before its post is converted.
+    # Its references take their numbers from the post: from the converted
+    # content when there is one, and otherwise from the tags in the source,
+    # which are in the same order. A missing target is the post's error to report.
+    def number_excerpt(excerpt, html)
+      return html unless html&.include?("data-ref")
+
+      post = excerpt.doc
+      found = post.content.to_s.scan(TARGET)
+      found = source_targets(post.content.to_s) if found.empty?
+      targets = targets(found.uniq(&:first), post)
+      html.gsub(LINK) do
+        id = Regexp.last_match(1)
+        text = targets[id] ? CGI.escapeHTML(targets[id]) : id
+        %(<a class="datalog-ref" href="#{post.site.baseurl}#{post.url}##{id}" data-ref="#{id}">#{text}</a>)
+      end
+    end
+
+    # [id, kind, label] for each numbered tag in a page's source.
+    def source_targets(source)
+      source.scan(SOURCE_TAG).filter_map do |kind, markup|
+        attributes = markup.scan(/(\w+)=["']([^"']*)["']/).to_h
+        [attributes["id"], kind, attributes["label"]] if attributes["id"]
+      end
+    end
+
+    # The id => "Figure 2" of every [id, kind, label] target, numbered per kind in
+    # page order. A target with its own label does not take a number.
+    def targets(found, document)
+      counts = Hash.new(0)
+      found.each_with_object({}) do |(id, kind, custom), targets|
+        if targets.key?(id)
+          raise Jekyll::Errors::FatalException,
+                "#{document.relative_path} has two numbered figures, tables or statements with the id " \
+                "\"#{id}\"; each id has to be unique"
+        end
+
+        number = custom ? CGI.unescapeHTML(custom) : (counts[kind] += 1)
+        targets[id] = "#{label(document, kind)} #{number}"
+      end
+    end
+
+    def link_references(content, targets, document)
+      missing = content.scan(LINK).flatten.uniq - targets.keys
+      unless missing.empty?
+        raise Jekyll::Errors::FatalException,
+              "#{document.relative_path} refers to #{missing.map { |id| "\"#{id}\"" }.join(', ')}, which no " \
+              "numbered figure, table or statement on the page has as its id"
+      end
+
+      content.gsub(LINK) do
+        id = Regexp.last_match(1)
+        %(<a class="datalog-ref" href="##{id}" data-ref="#{id}">#{CGI.escapeHTML(targets[id])}</a>)
+      end
+    end
+
+    def label(document, kind)
+      site = document.site
+      locale = I18n.locale_code(site, document.data["lang"])
+      I18n.lookup(site, locale, "references.#{kind}") || KINDS.fetch(kind)
+    end
+
+    def validate_label(label, tag)
+      return if label.nil? || label.match?(CUSTOM_LABEL)
+
+      raise Liquid::ArgumentError,
+            "{% #{tag} %} takes a label of letters, digits, \".\", \"'\", \"*\" or \"-\", such as label=\"A\"; " \
+            "got #{label.inspect}"
+    end
+
+    def validate_id(id, tag)
+      return id if id.to_s.match?(ID)
+
+      raise Liquid::ArgumentError,
+            "{% #{tag} %} needs an id that starts with a letter and holds only letters, digits, " \
+            "\"-\", \"_\", \".\" or \":\", such as id=\"fig-power\"; got #{id.inspect}"
+    end
+
+    # key="value", key='value' or key=variable.
+    def attributes(markup, context)
+      markup.scan(/(\w+)=(?:"([^"]*)"|'([^']*)'|([\w.\[\]-]+))/).to_h do |key, double, single, variable|
+        [key, double || single || context[variable].to_s]
+      end
+    end
+
+    def markdown(context, text)
+      site = context.registers[:site]
+      site.find_converter_instance(Jekyll::Converters::Markdown).convert(text.to_s.strip)
+    end
+
+    # A caption of one paragraph loses its <p>, which a <figcaption> or <caption> does not need.
+    def inline(html)
+      html = html.strip
+      paragraph = html.match(%r{\A<p>(.*)</p>\z}m)
+      paragraph && !paragraph[1].include?("<p>") ? paragraph[1] : html
+    end
+  end
+
+  class FigureTag < Liquid::Block
+    def initialize(tag_name, markup, options)
+      super
+      @markup = markup
+    end
+
+    def render(context)
+      attributes = References.attributes(@markup, context)
+      id = References.validate_id(attributes["id"], "figure")
+      src = attributes["src"].to_s
+      raise Liquid::ArgumentError, "{% figure id=\"#{id}\" %} needs a src, the image it shows" if src.empty?
+      if attributes["alt"].to_s.strip.empty?
+        raise Liquid::ArgumentError, "{% figure id=\"#{id}\" %} needs alt text for its image"
+      end
+
+      src = "#{context.registers[:site].config['baseurl'].to_s.chomp('/')}#{src}" if src.start_with?("/")
+      caption = References.inline(References.markdown(context, super))
+      classes = ["datalog-figure", attributes["class"]].compact.join(" ")
+
+      alt = CGI.escapeHTML(attributes["alt"])
+      %(<figure class="#{CGI.escapeHTML(classes)}" id="#{id}" data-ref-target="#{id}" data-ref-kind="figure">) +
+        %(<img src="#{CGI.escapeHTML(src)}" alt="#{alt}" loading="lazy" decoding="async">) +
+        %(<figcaption><span class="datalog-ref-label" data-ref-for="#{id}"></span> #{caption}</figcaption></figure>\n)
+    end
+  end
+
+  class TableTag < Liquid::Block
+    def initialize(tag_name, markup, options)
+      super
+      @markup = markup
+    end
+
+    # The body holds the caption and then a Markdown table.
+    def render(context)
+      id = References.validate_id(References.attributes(@markup, context)["id"], "table")
+      html = References.markdown(context, super)
+      tables = html.scan(/<table\b/).size
+      unless tables == 1
+        raise Liquid::ArgumentError, "{% table id=\"#{id}\" %} holds #{tables} tables; it needs one, after its caption"
+      end
+
+      caption, table = html.split(/(?=<table\b)/, 2)
+      caption = References.inline(caption)
+      numbered = table.sub(/<table\b([^>]*)>/) do
+        %(<table#{Regexp.last_match(1)} id="#{id}" data-ref-target="#{id}" data-ref-kind="table">) +
+          %(<caption><span class="datalog-ref-label" data-ref-for="#{id}"></span> #{caption}</caption>)
+      end
+      "#{numbered.strip}\n"
+    end
+  end
+
+  class ReferenceTag < Liquid::Tag
+    def initialize(tag_name, markup, options)
+      super
+      @id = References.validate_id(markup.strip, "ref")
+    end
+
+    def render(_context)
+      %(<a class="datalog-ref" href="##{@id}" data-ref="#{@id}">#{@id}</a>)
+    end
+  end
+end
+
+Liquid::Template.register_tag("figure", Datalog::FigureTag)
+Liquid::Template.register_tag("table", Datalog::TableTag)
+Liquid::Template.register_tag("ref", Datalog::ReferenceTag)
+
+Jekyll::Hooks.register %i[pages documents], :post_convert do |document|
+  Datalog::References.number(document)
+end
+
+Jekyll::Excerpt.prepend(Module.new do
+  # Excerpt#output renders once and keeps the result; numbering it is a quick gsub.
+  def output
+    Datalog::References.number_excerpt(self, super)
+  end
+end)