datalog-theme 0.8.0 → 0.9.1

data/_plugins/reproducibility.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Datalog
+  # The computational artifacts behind an article, for the "Reproduce this
+  # analysis" panel (_includes/components/reproducibility.html):
+  #
+  #   reproducibility:
+  #     code:
+  #       url: https://github.com/example/project
+  #       ref: 4f2c1ab                   # the commit, tag or branch the article used
+  #     data:
+  #       doi: 10.5281/zenodo.1234567    # or url:
+  #       version: v2
+  #     environment:
+  #       file: requirements.txt         # in the code repository at the ref, a site path or a URL
+  #       container: ghcr.io/example/project:1.4.0
+  #       archive: https://doi.org/10.5281/zenodo.7654321
+  #     notebook:
+  #       url: /notebooks/example/
+  #     results:
+  #       url: https://github.com/example/project/releases/tag/results-v1
+  #       version: results-v1
+  #
+  # Every artifact is optional, and each may be a bare URL. The panel shows
+  # what is given and claims nothing more: a link is a link, a ref is a ref.
+  # A URL that is not http(s), a site path or a DOI stops the build.
+  module Reproducibility
+    module_function
+
+    KINDS = %w[code data notebook environment results].freeze
+    # Where a ref and a file in the repository can be linked.
+    HOSTS = {
+      "github.com" => { tree: "/tree/%s", blob: "/blob/%s/%s" },
+      "gitlab.com" => { tree: "/-/tree/%s", blob: "/-/blob/%s/%s" }
+    }.freeze
+    URL = %r{\Ahttps?://[^\s"'<>]+\z}i
+    PATH = %r{\A/[^\s"'<>]*\z}
+
+    # The artifacts, in KINDS order, or nil when the page gives none.
+    def resolve(page, site)
+      value = Authors.value(page, "reproducibility")
+      return unless value.is_a?(Hash)
+
+      given = value.transform_keys(&:to_s)
+      baseurl = Authors.value(site, "baseurl").to_s
+      artifacts = KINDS.filter_map { |kind| artifact(kind, given[kind], given, page, baseurl) }
+      { "artifacts" => artifacts } unless artifacts.empty?
+    end
+
+    def artifact(kind, value, all, page, baseurl)
+      return if value.nil? || value == false || (value.is_a?(String) && value.strip.empty?)
+
+      given = value.is_a?(Hash) ? Authors.present(value) : { "url" => value.to_s }
+      url = link(given["url"] || doi_url(given["doi"]), page, "#{kind}.url", baseurl)
+      artifact = { "kind" => kind, "url" => url, "external" => external?(url), "version" => given["version"]&.to_s,
+                   "label" => given["label"] || display(url), "doi" => bare_doi(given["doi"]) }
+      artifact.merge!(code(given, url)) if kind == "code"
+      artifact.merge!(environment(given, all, page, baseurl)) if kind == "environment"
+      artifact = artifact.compact
+      artifact if artifact.values_at("url", "file", "container", "archive").any?
+    end
+
+    def code(given, url)
+      ref = given["ref"].to_s.strip
+      return {} if ref.empty?
+
+      { "ref" => ref, "ref_url" => host_url(url, :tree, ref) }
+    end
+
+    # The environment file lives in the code repository at the article's ref
+    # unless it is a site path or a URL of its own.
+    def environment(given, all, page, baseurl)
+      file = given["file"].to_s.strip
+      archive = link(given["archive"], page, "environment.archive", baseurl)
+      {
+        "file" => (file unless file.empty?),
+        "file_url" => (file_url(file, all["code"], page, baseurl) unless file.empty?),
+        "container" => given["container"]&.to_s,
+        "archive" => archive, "archive_label" => display(archive)
+      }
+    end
+
+    def file_url(file, code, page, baseurl)
+      own = file.match?(URL) || file.match?(PATH) || file.match?(/\Adoi:/i)
+      return link(file, page, "environment.file", baseurl) if own
+
+      code = code.is_a?(Hash) ? Authors.present(code) : { "url" => code.to_s }
+      code_url = link(code["url"], page, "code.url", baseurl)
+      ref = code["ref"].to_s.strip
+      host_url(code_url, :blob, ref.empty? ? "HEAD" : ref, file)
+    end
+
+    # A page of a known host under the repository URL, such as a tree or a blob.
+    def host_url(url, kind, *parts)
+      return unless url
+
+      uri = URI.parse(url)
+      host = uri.host.to_s.downcase.sub(/\Awww\./, "")
+      pattern = HOSTS.dig(host, kind)
+      return unless pattern
+
+      root = if host == "github.com"
+               uri.path.split("/").reject(&:empty?).first(2).join("/")
+             else
+               uri.path.sub(%r{/-/.*}, "").delete_prefix("/")
+             end
+      root = root.chomp("/").delete_suffix(".git")
+      # A ref is one route argument; a file retains its directory separators.
+      encoded = parts.each_with_index.map do |part, index|
+        index.zero? ? URI.encode_www_form_component(part).gsub("+", "%20") : encode_path(part)
+      end
+      "#{uri.scheme}://#{host}/#{root}#{format(pattern, *encoded)}"
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    # An http(s) URL as given, a site path with the baseurl, or a DOI as its
+    # URL; anything else, such as a javascript: URL or an address without its
+    # scheme, stops the build.
+    def link(value, page, field, baseurl)
+      text = value.to_s.strip
+      return if text.empty?
+      return doi_url(text) if text.match?(/\Adoi:/i)
+      return text if text.match?(URL)
+      return "#{baseurl}#{text}" if text.match?(PATH)
+
+      raise Jekyll::Errors::FatalException,
+            "#{Authors.value(page, 'path')} reproducibility.#{field} is #{text.inspect}, which is not an http(s) " \
+            "URL, a site path starting with / or a doi:; give the whole address, such as https://github.com/example/project"
+    end
+
+    def bare_doi(doi)
+      text = doi.to_s.strip.sub(%r{\Ahttps?://(dx\.)?doi\.org/}i, "").sub(/\Adoi:\s*/i, "")
+      text unless text.empty?
+    end
+
+    def doi_url(doi)
+      bare = bare_doi(doi)
+      "https://doi.org/#{encode_path(bare)}" if bare
+    end
+
+    def encode_path(value)
+      value.to_s.split("/", -1).map { |part| URI.encode_www_form_component(part).gsub("+", "%20") }.join("/")
+    end
+
+    # What a link reads: the address without its scheme, or the site path.
+    def display(url)
+      return url unless external?(url)
+
+      url.sub(%r{\Ahttps?://(www\.)?}i, "").chomp("/")
+    end
+
+    def external?(url)
+      url.to_s.match?(URL)
+    end
+  end
+
+  module ReproducibilityFilters
+    def page_reproducibility(page)
+      Reproducibility.resolve(page, @context["site"])
+    end
+  end
+end
+
+Liquid::Template.register_filter(Datalog::ReproducibilityFilters)

data/_plugins/responsive_content.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Datalog
+  # A table keeps its native semantics and desktop width while its enclosing
+  # region can scroll with either touch or the keyboard on a narrow screen.
+  module ResponsiveContent
+    module_function
+
+    def process(document)
+      return unless document.output_ext == ".html" && document.content.to_s.include?("<table")
+
+      html = Nokogiri::HTML5.fragment(document.content)
+      tables = html.css("table").to_a
+      tables.reject! do |table|
+        table["class"].to_s.split.include?("rouge-table") || table.ancestors(".content-table").any?
+      end
+      return if tables.empty?
+
+      locale = I18n.locale_code(document.site, document.data["lang"])
+      label = I18n.lookup(document.site, locale, "references.table") || "Table"
+      tables.each_with_index do |table, index|
+        wrapper = Nokogiri::XML::Node.new("div", html)
+        wrapper["class"] = "content-table"
+        wrapper["role"] = "region"
+        wrapper["tabindex"] = "0"
+        caption = table.at_css("caption")&.text.to_s.strip
+        wrapper["aria-label"] = caption.empty? ? "#{label} #{index + 1}" : caption
+        table.add_previous_sibling(wrapper)
+        wrapper.add_child(table)
+      end
+      document.content = html.to_html
+    end
+  end
+end
+
+Jekyll::Hooks.register %i[pages documents], :post_convert do |document|
+  Datalog::ResponsiveContent.process(document)
+end

data/_plugins/revisions.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Datalog
+  # The revision history of an article, for a post that is corrected or
+  # rewritten while keeping its URL:
+  #
+  #   revisions:
+  #     - date: 2026-09-16
+  #       type: correction
+  #       summary: Replaced the sample-size rules with model diagnostics.
+  #       details_url: https://github.com/example/repo/pull/425
+  #     - date: 2024-03-12
+  #       type: update
+  #       summary: Updated the code examples for the current SciPy.
+  #
+  # Before the site renders, each page's list is checked, its dates are
+  # parsed and its entries sorted newest first, so the includes read one
+  # shape. A correction or an update is substantive: the newest one becomes
+  # `revision_notice`, which the post layout announces under the metadata.
+  # A review or an editorial change appears in the history only.
+  #
+  # Every revision but a review changed the article, so the newest one sets
+  # `last_modified_at` when it is later than the date the page gives, and
+  # the JSON-LD, the microdata, the feed and the sitemap all carry it.
+  module Revisions
+    module_function
+
+    TYPES = %w[correction update review editorial].freeze
+    SUBSTANTIVE = %w[correction update].freeze
+    DEFAULT_TYPE = "update"
+
+    def normalize!(document)
+      data = document.data
+      data["last_modified_at"] ||= to_time(data["updated"]) if data["updated"]
+      return unless data.key?("revisions")
+
+      revisions = entries(data["revisions"], document)
+      data["revisions"] = revisions
+      notice = revisions.find { |revision| revision["substantive"] }
+      data["revision_notice"] = notice unless data["revision_notice"] == false
+
+      changed = revisions.find { |revision| revision["type"] != "review" }
+      modified = to_time(data["last_modified_at"] || data["updated"])
+      data["last_modified_at"] = changed["date"] if changed && (modified.nil? || changed["date"] > modified)
+    end
+
+    # Newest first; revisions on one day keep their order.
+    def entries(list, document)
+      unless list.is_a?(Array)
+        stop(document, "has revisions that is not a list; each revision is a map with a date, a summary and, " \
+                       "if wanted, a type and a details_url")
+      end
+
+      revisions = list.each_with_index.map { |entry, index| revision(entry, index + 1, document) }
+      revisions.each_with_index.sort_by { |revision, index| [-revision["date"].to_i, index] }.map(&:first)
+    end
+
+    def revision(entry, number, document)
+      stop(document, "revision #{number} is not a map with a date and a summary") unless entry.is_a?(Hash)
+
+      entry = entry.transform_keys(&:to_s)
+      type = (entry["type"] || DEFAULT_TYPE).to_s.strip.downcase
+      unless TYPES.include?(type)
+        stop(document, "revision #{number} has the type #{entry['type'].inspect}; it takes #{TYPES.join(', ')}")
+      end
+      summary = entry["summary"].to_s.strip
+      stop(document, "revision #{number} needs a summary saying what changed") if summary.empty?
+      date = to_time(entry["date"])
+      unless date
+        stop(document, "revision #{number} has the date #{entry['date'].inspect}, which is not a date such as " \
+                       "2026-09-16")
+      end
+
+      details = entry["details_url"].to_s.strip
+      { "date" => date, "type" => type, "summary" => summary, "details_url" => (details unless details.empty?),
+        "substantive" => SUBSTANTIVE.include?(type) }.compact
+    end
+
+    def stop(document, problem)
+      raise Jekyll::Errors::FatalException, "#{document.relative_path} #{problem}"
+    end
+
+    # A Date, a Time or a string naming a day, such as "2026-09-16".
+    def to_time(value)
+      case value
+      when Time then value
+      when Date then value.to_time
+      when String
+        parts = Date._parse(value)
+        Time.parse(value) if parts[:year] && parts[:mon] && parts[:mday]
+      end
+    end
+  end
+end
+
+Jekyll::Hooks.register :site, :post_read do |site|
+  site.documents.each { |document| Datalog::Revisions.normalize!(document) }
+  site.pages.each { |page| Datalog::Revisions.normalize!(page) }
+end

data/_plugins/scholarly.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Datalog
+  # Which pages get scholarly discovery metadata (_includes/meta/scholarly.html):
+  # the Highwire meta tags Google Scholar and reference managers read, and
+  # their Dublin Core equivalents. Not every post is a paper, so the tags are
+  # opt-in:
+  #
+  #   scholarly: true        # front matter: this page is a research article
+  #   scholarly: false       # front matter: this one is not, whatever the site says
+  #
+  #   scholarly: true        # _config.yml: every post and research article
+  #   scholarly: [notebooks] # _config.yml: these collections or layouts as well
+  #
+  # A page with the research layout, or in a research collection, is
+  # scholarly unless it says otherwise.
+  module Scholarly
+    module_function
+
+    ALWAYS = %w[research].freeze
+    POSTS = %w[posts post].freeze
+
+    def scholarly?(page, site)
+      own = Authors.value(page, "scholarly")
+      return own == true unless own.nil?
+
+      kinds = kinds(Authors.value(site, "scholarly"))
+      [Authors.value(page, "layout"), Authors.value(page, "collection")].any? { |kind| kinds.include?(kind.to_s) }
+    end
+
+    # The layouts and collections the site's setting covers, besides research.
+    def kinds(setting)
+      case setting
+      when true then ALWAYS + POSTS
+      when Array then ALWAYS + setting.map(&:to_s)
+      when String then ALWAYS + setting.split(/[\s,]+/)
+      else ALWAYS
+      end
+    end
+  end
+
+  module ScholarlyFilters
+    # JSON embedded in a script must not contain an HTML closing tag.
+    def jsonify_script(value)
+      jsonify(value).gsub("<", '\\u003c').gsub("\u2028", '\\u2028').gsub("\u2029", '\\u2029')
+    end
+
+    # A Liquid filter's name cannot end with "?".
+    def scholarly(page) # rubocop:disable Naming/PredicateMethod
+      Scholarly.scholarly?(page, @context["site"])
+    end
+  end
+end
+
+Liquid::Template.register_filter(Datalog::ScholarlyFilters)

data/_plugins/series.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Datalog
+  # Article series: multi-part writing a reader follows in order, whatever
+  # was published in between.
+  #
+  #   series:                       # front matter, as a map
+  #     id: missing-data
+  #     title: Missing Data and Statistical Inference
+  #     order: 3
+  #
+  #   series: missing-data          # or flat
+  #   series_title: Missing Data and Statistical Inference
+  #   series_order: 3
+  #
+  #   missing-data:                 # _data/series.yml, so the title lives once
+  #     title: Missing Data and Statistical Inference
+  #     description: Four parts, from the missing-data mechanisms to sensitivity analysis.
+  #
+  # Before the site renders, every part is checked (an order that is missing,
+  # not a whole number or taken by another part stops the build), the parts
+  # are put in order, and each page's `series` becomes one shape: id, title,
+  # description, order, position, count, parts (title, url, order, position,
+  # current), previous and next. _includes/components/series-nav.html reads it.
+  module Series
+    module_function
+
+    def normalize!(site)
+      documents = site.documents + site.pages
+      registry = site.data["series"].is_a?(Hash) ? site.data["series"] : {}
+      documents.filter_map { |document| part(document) }.group_by { |part| part[:id] }.each do |id, parts|
+        check_orders!(id, parts)
+        meta = registry[id].is_a?(Hash) ? registry[id] : {}
+        resolve!(id, parts.sort_by { |part| part[:order] }, meta)
+      end
+    end
+
+    # The document's part of a series, as {doc, id, order, title}, or nil.
+    def part(document)
+      data = document.data
+      value = data["series"]
+      return if value.nil? || value == false || (value.is_a?(String) && value.strip.empty?)
+
+      given = case value
+              when Hash then value.transform_keys(&:to_s)
+              when String, Symbol then { "id" => value.to_s }
+              else stop(document, "has a series that is neither a name nor a map with an id and an order")
+              end
+      id = given["id"].to_s.strip
+      stop(document, "has a series without an id, such as series: missing-data") if id.empty?
+
+      order = given["order"] || data["series_order"]
+      unless whole_number?(order)
+        stop(document, "is part of the series \"#{id}\" without an order; give the part a whole number from 1, " \
+                       "such as order: 2")
+      end
+
+      { doc: document, id: id, order: order.to_i, title: given["title"] || data["series_title"] }
+    end
+
+    def whole_number?(value)
+      (value.is_a?(Integer) && value >= 1) || (value.is_a?(String) && value.match?(/\A[1-9]\d*\z/))
+    end
+
+    def check_orders!(id, parts)
+      parts.group_by { |part| part[:order] }.each_value do |same|
+        next if same.size == 1
+
+        paths = same.map { |part| part[:doc].relative_path }.sort.join(" and ")
+        raise Jekyll::Errors::FatalException,
+              "#{paths} are both part #{same.first[:order]} of the series \"#{id}\"; each part needs its own order"
+      end
+    end
+
+    # Writes each part's `series` from the ordered parts and the data file's entry.
+    def resolve!(id, ordered, meta)
+      title = meta["title"] || ordered.filter_map { |part| part[:title] }.first || titleize(id)
+      summaries = ordered.each_with_index.map do |part, index|
+        { "title" => part[:doc].data["title"], "url" => part[:doc].url, "order" => part[:order],
+          "position" => index + 1 }
+      end
+      ordered.each_with_index do |part, index|
+        part[:doc].data["series"] = {
+          "id" => id, "title" => title, "description" => meta["description"],
+          "order" => part[:order], "position" => index + 1, "count" => ordered.size,
+          "parts" => summaries.map { |summary| summary.merge("current" => summary["url"] == part[:doc].url) },
+          "previous" => (summaries[index - 1] if index.positive?), "next" => summaries[index + 1]
+        }.compact
+      end
+    end
+
+    def titleize(id)
+      id.tr("-_", "  ").split.map(&:capitalize).join(" ")
+    end
+
+    def stop(document, problem)
+      raise Jekyll::Errors::FatalException, "#{document.relative_path} #{problem}"
+    end
+  end
+end
+
+Jekyll::Hooks.register :site, :post_read do |site|
+  Datalog::Series.normalize!(site)
+end

data/_plugins/statements.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Datalog
+  # Theorems, lemmas and the other statements of mathematical writing, and
+  # proofs. Articles marked them with a blockquote and a bold "Theorem 1.",
+  # typed by hand:
+  #
+  #   {% theorem id="thm-consistency" title="Consistency" %}
+  #   Let $\hat\theta_n$ be ...
+  #   {% endtheorem %}
+  #
+  #   {% proof for="thm-consistency" %}
+  #   ...
+  #   {% endproof %}
+  #
+  # Statements are numbered with figures and tables (_plugins/references.rb):
+  # each kind counts on its own, {% ref thm-consistency %} reads "Theorem 1",
+  # and a duplicate id stops the build. `label="A"` names a statement
+  # "Theorem A" instead of numbering it. A proof is not numbered; with `for`
+  # its heading reads "Proof of Theorem 1".
+  class StatementTag < Liquid::Block
+    def initialize(tag_name, markup, options)
+      super
+      @kind = tag_name
+      @markup = markup
+    end
+
+    def render(context)
+      attributes = References.attributes(@markup, context, @kind)
+      id = References.validate_id(attributes["id"], @kind)
+      custom = attributes["label"]
+      References.validate_label(custom, @kind)
+      body = References.markdown(context, super)
+
+      number = custom ? %( data-ref-number="#{CGI.escapeHTML(custom)}") : ""
+      title = attributes["title"].to_s.strip
+      title = title.empty? ? "" : %( <span class="datalog-statement__title">(#{CGI.escapeHTML(title)})</span>)
+      %(<div class="datalog-statement datalog-statement--#{@kind}" role="group" aria-labelledby="#{id}-heading" ) +
+        %(id="#{id}" data-ref-target="#{id}" data-ref-kind="#{@kind}"#{number}>) +
+        %(<p class="datalog-statement__heading" id="#{id}-heading">) +
+        %(<span class="datalog-ref-label" data-ref-for="#{id}" data-ref-end=""></span>#{title}.</p>) +
+        %(<div class="datalog-statement__body">#{body.strip}</div></div>\n)
+    end
+  end
+
+  class ProofTag < Liquid::Block
+    def initialize(tag_name, markup, options)
+      super
+      @markup = markup
+    end
+
+    def render(context)
+      attributes = References.attributes(@markup, context, "proof")
+      target = attributes["for"]
+      body = References.markdown(context, super)
+      heading_id = "proof-#{target ? References.validate_id(target, 'proof') : Statements.next_proof(context)}"
+      heading = if target
+                  link = %(<a class="datalog-ref" href="##{target}" data-ref="#{target}">#{target}</a>)
+                  I18n.translate(context, "references.proof_of", "target" => link)
+                else
+                  CGI.escapeHTML(I18n.translate(context, "references.proof"))
+                end
+      end_mark = %(<p class="datalog-proof__end"><span aria-hidden="true">∎</span></p>)
+      end_mark = "" if attributes["qed"] == "false"
+
+      %(<div class="datalog-proof" role="group" aria-labelledby="#{heading_id}">) +
+        %(<p class="datalog-proof__heading" id="#{heading_id}">#{heading}.</p>) +
+        %(<div class="datalog-proof__body">#{body.strip}</div>#{end_mark}</div>\n)
+    end
+  end
+
+  module Statements
+    module_function
+
+    KINDS = %w[theorem lemma proposition corollary definition assumption example remark].freeze
+
+    # Proofs without a statement are numbered in the page for their heading ids only.
+    def next_proof(context)
+      context.registers[:datalog_proofs] = context.registers[:datalog_proofs].to_i + 1
+    end
+  end
+end
+
+Datalog::Statements::KINDS.each { |kind| Liquid::Template.register_tag(kind, Datalog::StatementTag) }
+Liquid::Template.register_tag("proof", Datalog::ProofTag)

data/_sass/_base.scss

@@ -12,7 +12,14 @@
 
 html {
   font-size: $font-size-root;
-  scroll-behavior: smooth;
+}
+
+// Anchor links, and the theme's scripts, which pass no scroll behavior, follow
+// this rule, so a reader who asks for reduced motion jumps to the target.
+@media (prefers-reduced-motion: no-preference) {
+  html {
+    scroll-behavior: smooth;
+  }
 }
 
 body {
@@ -40,6 +47,11 @@ iframe {
   max-width: 100%;
 }
 
+img,
+video {
+  height: auto;
+}
+
 a {
   color: $color-accent-primary;
   text-decoration-thickness: 0.12em;