datalog-theme 0.8.0 → 0.9.0

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)
+      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)
+      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 {

data/_sass/_comments-thread.scss

@@ -0,0 +1,159 @@
+@use 'sass:map';
+
+@use 'variables' as *;
+
+// The comments thread of the `api` provider (components/comments-thread.html,
+// assets/js/comments/thread.js). The form itself is a .service-form
+// (_service-forms.scss).
+
+.comments-thread {
+  max-width: $max-width-reading;
+}
+
+.comments-thread__status {
+  margin: 0 0 map.get($spacing, 3);
+  color: $color-ink-500;
+  font-size: map.get($font-size-scale, sm);
+
+  .comments-thread[data-state='error'] & {
+    color: $color-danger-700;
+  }
+}
+
+.comments-thread__noscript {
+  margin: 0 0 map.get($spacing, 3);
+  color: $color-ink-500;
+}
+
+.comments-thread__list,
+.comments-thread__replies {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.comments-thread__list {
+  display: grid;
+  gap: map.get($spacing, 3);
+  margin-bottom: map.get($spacing, 5);
+}
+
+// display: grid and display: flex would override the hidden attribute.
+.comments-thread__list[hidden],
+.comments-form__replying[hidden] {
+  display: none;
+}
+
+.comments-thread__replies {
+  display: grid;
+  gap: map.get($spacing, 3);
+  margin-top: map.get($spacing, 3);
+  padding-left: map.get($spacing, 4);
+  border-left: 2px solid rgba($color-neutral-500, 0.25);
+}
+
+.comment__card {
+  padding: map.get($spacing, 3) map.get($spacing, 4);
+  border-radius: map.get($radius, md);
+  background: rgba($color-neutral-500, 0.06);
+}
+
+.comment--pending > .comment__card {
+  border: 1px dashed rgba($color-neutral-500, 0.5);
+  background: transparent;
+}
+
+.comment__meta {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: map.get($spacing, 2);
+  margin-bottom: map.get($spacing, 2);
+  font-size: map.get($font-size-scale, sm);
+}
+
+.comment__author {
+  font-weight: 600;
+  color: $color-ink-900;
+}
+
+.comment__time {
+  color: $color-ink-500;
+}
+
+.comment__pending {
+  padding: 0 map.get($spacing, 2);
+  border-radius: map.get($radius, sm);
+  background: rgba($color-neutral-500, 0.15);
+  color: $color-ink-700;
+  font-size: map.get($font-size-scale, xs);
+}
+
+.comment__body {
+  overflow-wrap: anywhere;
+
+  p {
+    margin: 0 0 map.get($spacing, 2);
+  }
+
+  p:last-child {
+    margin-bottom: 0;
+  }
+}
+
+.comment__reply {
+  margin-top: map.get($spacing, 2);
+}
+
+.comments-form__heading {
+  margin: 0 0 map.get($spacing, 2);
+  font-size: map.get($font-size-scale, md);
+}
+
+.comments-form__replying {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: map.get($spacing, 2);
+  margin: 0 0 map.get($spacing, 3);
+  color: $color-ink-700;
+  font-size: map.get($font-size-scale, sm);
+}
+
+body.dark-mode {
+  .comments-thread__status,
+  .comments-thread__noscript,
+  .comment__time {
+    color: $dark-ink-500;
+  }
+
+  .comments-thread[data-state='error'] .comments-thread__status {
+    color: $color-danger-300;
+  }
+
+  .comment__card {
+    background: rgba($dark-ink-500, 0.12);
+  }
+
+  .comment--pending > .comment__card {
+    border-color: rgba($dark-ink-500, 0.5);
+    background: transparent;
+  }
+
+  .comment__author {
+    color: $dark-ink-900;
+  }
+
+  .comment__pending,
+  .comments-form__replying {
+    color: $dark-ink-700;
+  }
+
+  .comment__pending {
+    background: rgba($dark-ink-500, 0.2);
+  }
+
+  .comments-thread__replies {
+    border-left-color: rgba($dark-ink-500, 0.35);
+  }
+}