datalog-theme 0.8.0 → 0.9.1

data/_plugins/licenses.rb

@@ -0,0 +1,147 @@
+# 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)
+      own_only = OWN_LICENSE.include?(Authors.value(page, "collection").to_s)
+      fallback = Authors.value(site, site_key) unless own_only
+      return fallback if value.nil? || value == true
+
+      if value.is_a?(Hash) && !Authors.present(value).keys.intersect?(%w[id name url])
+        defaults = fallback.is_a?(Hash) ? Authors.present(fallback) : { "name" => fallback }
+        return defaults.merge(Authors.present(value))
+      end
+
+      value
+    end
+
+    def resolve(value, page, site)
+      return if value.nil? || value == false || (value.is_a?(String) && value.strip.empty?)
+      unless value.is_a?(String) || value.is_a?(Hash)
+        raise Jekyll::Errors::FatalException, "#{Authors.value(page, 'path')} license must be a name, a map or false"
+      end
+
+      given = value.is_a?(Hash) ? Authors.present(value) : { "name" => value.to_s.strip }
+      return unless given.keys.intersect?(%w[id name url])
+
+      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/)
+      return text if text.match?(/\A\d{4}[-–]\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

@@ -26,6 +26,16 @@ module MathPreprocessor
       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"
@@ -57,22 +67,43 @@ module MathPreprocessor
     def process
       return @content unless @content&.match?(/\$|\\\(|\\\[|\\begin\{/)
 
-      code = []
+      @segments = []
       processed = CODE_PATTERNS.reduce(@content.dup) do |text, pattern|
-        text.gsub(pattern) do |match|
-          code << match
-          "\x00#{code.size - 1}\x00"
-        end
+        text.gsub(pattern) { |match| mask(match) }
       end
+      processed = normalize_inline_dollars(processed)
       processed = apply_patterns(processed, DISPLAY_PATTERNS, display: true)
       processed = apply_patterns(processed, INLINE_PATTERNS, display: false)
       # A segment set aside can contain the placeholder of an earlier one.
-      processed = processed.gsub(PLACEHOLDER) { code[Regexp.last_match(1).to_i] } while processed.match?(PLACEHOLDER)
+      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
+
+    # Kramdown accepts $$...$$ inside prose as inline math. A div there is
+    # escaped by Markdown and leaks its attributes into the visible article.
+    # Normalize before wrapping; code is already masked and standalone or
+    # multiline display equations retain their original delimiters.
+    def normalize_inline_dollars(text)
+      text.gsub(DISPLAY_PATTERNS.first[:regex]) do |expression|
+        match = Regexp.last_match
+        body = match[:body]
+        next expression if body.include?("\n") || body.strip.empty?
+
+        before = match.pre_match.split("\n", -1).last.to_s
+        after = match.post_match.split("\n", 2).first.to_s
+        next expression unless before.match?(/\S/) || after.match?(/\S/)
+
+        "$#{body.strip}$"
+      end
+    end
+
     def apply_patterns(text, patterns, display: false)
       patterns.reduce(text) do |result, pattern|
         result.gsub(pattern[:regex]) do |match|
@@ -81,8 +112,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
@@ -103,6 +137,9 @@ module MathPreprocessor
         "aria-label" => alt_text,
         "tabindex" => "0"
       }
+      # Kramdown must not interpret TeX's escaped delimiters or underscores as
+      # Markdown inside an inline HTML span.
+      attributes["markdown"] = "0" unless display
 
       attribute_string = attributes.map do |key, value|
         next if value.nil? || value.strip.empty?
@@ -110,7 +147,7 @@ module MathPreprocessor
         %(#{key}="#{CGI.escapeHTML(value)}")
       end.compact.join(" ")
 
-      inner = "#{open}#{latex}#{close}"
+      inner = CGI.escapeHTML("#{open}#{latex}#{close}")
       "<#{tag} #{attribute_string}>#{inner}</#{tag}>"
     end
 
@@ -195,9 +232,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\{/)
@@ -207,6 +244,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/references.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "strscan"
+
+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="([^"]+)")?
+              ([ ]data-ref-numbered="true")?/x
+    # 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")
+
+      # Feeds and listings embed content that has already been numbered on its
+      # own page. Only process this document's remaining placeholders.
+      targets = targets(content.scan(TARGET).reject { |entry| entry[3] }, document)
+      content = content.gsub(TARGET) do |target|
+        Regexp.last_match(4) ? target : %(#{target} data-ref-numbered="true")
+      end
+      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)
+        label = CGI.escapeHTML(targets[id])
+        %(<a class="datalog-ref" href="##{id}" data-ref="#{id}" data-ref-numbered="true">#{label}</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, tag = "reference")
+      scanner = StringScanner.new(markup)
+      result = {}
+      until scanner.eos?
+        scanner.skip(/\s+/)
+        break if scanner.eos?
+
+        unless scanner.scan(/(\w+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|([\w.\[\]-]+))(?=\s|\z)/m)
+          page = context.registers[:page] || {}
+          raise Liquid::ArgumentError,
+                "#{page['path'] || page['url']} {% #{tag} %} has invalid attributes near #{scanner.rest.inspect}"
+        end
+        # Ruby 3.2's StringScanner#captures returns "" for unmatched groups.
+        # values_at preserves nil so quoted literals stay distinct from variables.
+        key, double, single, variable = scanner.values_at(1, 2, 3, 4)
+        result[key] = variable ? context[variable].to_s : (double || single).gsub(/\\([\\"'])/, '\\1')
+      end
+      result
+    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, "figure")
+      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, "table")["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)