pandorga 1.2.1

data/lib/pandorga/registry/schema.yml

@@ -0,0 +1,115 @@
+# Registry configuration schema for `pandorga:` in `_config.yml`.
+# Source of truth for docs/configuration.md (PLT-AC-11).
+# Validated at build time by PandorgaRegistry.validate! and related helpers.
+
+identity:
+  title: "`pandorga.identity`"
+  keys:
+    name:
+      type: string
+      required: true
+      notes: Title suffix, default author, BibTeX
+    short_name:
+      type: string
+      required: false
+      notes: Shorter `<title>` suffix
+    url:
+      type: string
+      required: false
+      notes: Site canonical URL
+    locale:
+      type: string
+      required: false
+      notes: Default `en`
+
+content:
+  title: "`pandorga.content`"
+  intro: |
+    Legacy `content_api_base_url` still works as a fallback for `base_url`.
+  keys:
+    backend:
+      type: "`static` \\| `r2` \\| `object_store` \\| `s3`"
+      notes: "`static` serves JSON from `_site`. The others use `base_url` as the public object-store origin"
+    base_url:
+      type: string
+      notes: Public content origin when backend is not `static`
+
+home:
+  title: "`pandorga.home`"
+  keys:
+    hero_art:
+      type: string
+      notes: Include path for hero decoration (default `page/hero-default.html`)
+
+taxonomies:
+  title: "`pandorga.taxonomies`"
+  prose: |
+    Closed tag vocabularies per collection (`tags`, `max`, `min`). Page-local
+    `pandorga.pages[].taxonomy` is also accepted when a collection has no top-level
+    entry.
+
+pages:
+  title: "`pandorga.pages[]`"
+  footer: |
+    Duplicate `key`, unknown `template`, or conflicting `path` fails the build.
+  keys:
+    key:
+      type: string
+      required: true
+      notes: Unique page id
+    template:
+      type: string
+      required: true
+      notes: One of `cv`, `articles`, `blog`, `media`, `network`, `bibliography`, `portfolio`
+    layout:
+      type: string
+      required: false
+      notes: Jekyll layout override (default from template)
+    collection:
+      key_label: "collection` / `collections"
+      type: string / map
+      required: "template-dependent"
+      notes: Content folders
+    path:
+      type: string
+      required: true
+      notes: Listing URL
+    detail:
+      type: string
+      required: false
+      notes: Detail route pattern
+    nav:
+      type: "map \\| `false`"
+      required: false
+      notes: "`{ group, icon }` or hide"
+    home:
+      type: "map \\| `false`"
+      required: false
+      notes: Home band options; omit for template defaults
+    taxonomy:
+      type: map
+      required: false
+      notes: Tag vocabulary for the page
+    accent:
+      type: string
+      required: false
+      notes: Page accent token
+    language:
+      type: string
+      required: false
+      notes: Listing / home band language
+  home_attributes:
+    title: "`home` attributes"
+    entries:
+      - key: "`band: hero`"
+        notes: Page feeds the hero (CV); not a separate band
+      - key: "`band: index` + `group`"
+        notes: Joins a shared index panel group
+      - key: "`featured`"
+        notes: Lead card for writing bands
+      - key: "`limit`"
+        notes: Max items in the band
+      - key: "`cta`"
+        notes: Listing CTA label (default `View all`)
+      - key: "`false`"
+        notes: Omit from the homepage

data/lib/pandorga/registry.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+# Page registry helpers (no Jekyll dependency — safe for the exporter CLI).
+# Refs: PLT-AC-3, PLT-AC-5
+
+module PandorgaRegistry
+  KNOWN_TEMPLATES = %w[
+    cv articles blog media network bibliography portfolio
+  ].freeze
+
+  # Template key → Jekyll layout name (existing top-level layouts).
+  TEMPLATE_LAYOUTS = {
+    "cv" => "cv",
+    "articles" => "articles",
+    "blog" => "blog",
+    "media" => "resources",
+    "network" => "network",
+    "bibliography" => "bibliography",
+    "portfolio" => "projects"
+  }.freeze
+
+  # Shell collections loaded from content/ for timeline / CV / media.
+  DEFAULT_SHELL_COLLECTIONS = {
+    "products" => "collections/products",
+    "projects" => "collections/projects",
+    "jobs" => "collections/jobs",
+    "resources" => "collections/resources"
+  }.freeze
+
+  OBJECT_STORE_BACKENDS = %w[r2 object_store s3].freeze
+
+  module_function
+
+  def pages(config)
+    raw = config.dig("pandorga", "pages")
+    return [] unless raw.is_a?(Array)
+
+    raw
+  end
+
+  def validate!(pages)
+    keys = []
+    paths = []
+    pages.each_with_index do |page, i|
+      raise ArgumentError, "pandorga.pages[#{i}] must be a mapping" unless page.is_a?(Hash)
+
+      key = page["key"].to_s
+      raise ArgumentError, "pandorga.pages[#{i}]: missing key" if key.empty?
+      raise ArgumentError, "pandorga.pages: duplicate key #{key.inspect}" if keys.include?(key)
+
+      keys << key
+
+      template = page["template"].to_s
+      raise ArgumentError, "pandorga.pages[#{key}]: missing template" if template.empty?
+      unless KNOWN_TEMPLATES.include?(template)
+        raise ArgumentError,
+              "pandorga.pages[#{key}]: unknown template #{template.inspect} " \
+              "(known: #{KNOWN_TEMPLATES.join(', ')})"
+      end
+
+      path = page["path"].to_s
+      next if path.empty?
+      raise ArgumentError, "pandorga.pages: conflicting path #{path.inspect}" if paths.include?(path)
+
+      paths << path
+    end
+  end
+
+  def build_nav(pages)
+    groups = {}
+    order = []
+    pages.each do |page|
+      next unless page.is_a?(Hash)
+      next if page["nav"] == false
+
+      nav = page["nav"].is_a?(Hash) ? page["nav"] : {}
+      group = nav["group"] || "Pages"
+      unless groups.key?(group)
+        groups[group] = []
+        order << group
+      end
+      item = { "key" => page["key"] }
+      item["icon"] = nav["icon"] if nav["icon"]
+      groups[group] << item
+    end
+    order.map { |label| { "label" => label, "pages" => groups[label] } }
+  end
+
+  def layout_for(page)
+    return page["layout"].to_s unless page["layout"].to_s.empty?
+
+    template = page["template"].to_s
+    TEMPLATE_LAYOUTS.fetch(template, "pandorga/#{template}")
+  end
+
+  def writing_collections(pages)
+    map = {}
+    pages.each do |page|
+      next unless page.is_a?(Hash)
+      next unless %w[articles blog].include?(page["template"].to_s)
+
+      collection = page["collection"].to_s
+      next if collection.empty?
+
+      type = case collection
+             when "articles" then "article"
+             when "posts" then "post"
+             else collection.sub(/s\z/, "")
+             end
+      map[collection] = type
+    end
+    # Portfolio / CV keyed entries also feed the slim writing index.
+    pages.each do |page|
+      next unless page.is_a?(Hash)
+
+      case page["template"].to_s
+      when "portfolio"
+        c = page["collection"].to_s
+        map[c] = "project" unless c.empty?
+      when "cv"
+        cols = page["collections"]
+        next unless cols.is_a?(Hash)
+
+        products = cols["products"].to_s
+        map[products] = "product" unless products.empty?
+      end
+    end
+    map["products"] ||= "product"
+    map["projects"] ||= "project"
+    map
+  end
+
+  # Collection folders the shell injects at build time (jobs, projects, …).
+  def shell_collection_dirs(pages)
+    dirs = {}
+    pages.each do |page|
+      next unless page.is_a?(Hash)
+
+      template = page["template"].to_s
+      case template
+      when "portfolio"
+        name = page["collection"].to_s
+        dirs[name] = "collections/#{name}" unless name.empty?
+      when "media"
+        name = page["collection"].to_s
+        dirs[name] = "collections/#{name}" unless name.empty?
+      when "cv"
+        cols = page["collections"]
+        next unless cols.is_a?(Hash)
+
+        cols.each_value do |name|
+          n = name.to_s
+          next if n.empty? || n == "data" || n == "profile"
+
+          dirs[n] = "collections/#{n}"
+        end
+      end
+    end
+    dirs.empty? ? DEFAULT_SHELL_COLLECTIONS.dup : DEFAULT_SHELL_COLLECTIONS.merge(dirs)
+  end
+
+  # Adapter collections used for timeline derived export.
+  def adapter_collection_dirs(pages)
+    dirs = shell_collection_dirs(pages)
+    dirs.select { |name, _| %w[products projects jobs].include?(name) }
+  end
+
+  # Default home behaviour when `home` is omitted (PLT §5.2 / §5.4).
+  TEMPLATE_HOME_DEFAULTS = {
+    "cv" => { "band" => "hero" },
+    "articles" => { "featured" => true, "limit" => 3 },
+    "blog" => { "limit" => 4 },
+    "portfolio" => { "limit" => 4 },
+    "media" => { "band" => "index", "group" => "references" },
+    "network" => { "band" => "index", "group" => "references" },
+    "bibliography" => { "band" => "index", "group" => "references" }
+  }.freeze
+
+  # Homepage band plan in registry order (PLT §5.4).
+  # Hero-only pages (`home.band: hero`) are skipped — the hero is separate.
+  def home_bands(pages)
+    bands = []
+    pending_index = nil
+
+    flush_index = lambda do
+      return unless pending_index
+
+      bands << pending_index
+      pending_index = nil
+    end
+
+    pages.each do |page|
+      next unless page.is_a?(Hash)
+      next if page["home"] == false
+
+      home = resolve_home(page)
+      next if home["band"].to_s == "hero"
+
+      if home["band"].to_s == "index" || !home["group"].to_s.empty?
+        group = home["group"].to_s
+        group = "index" if group.empty?
+        if pending_index.nil? || pending_index["group"] != group
+          flush_index.call
+          pending_index = {
+            "kind" => "index",
+            "group" => group,
+            "section_key" => group == "references" ? "index" : group,
+            "pages" => []
+          }
+        end
+        pending_index["pages"] << page_band_meta(page, home)
+        next
+      end
+
+      flush_index.call
+      template = page["template"].to_s
+      bands << page_band_meta(page, home).merge(
+        "kind" => template,
+        "section_key" => page["key"].to_s
+      )
+    end
+    flush_index.call
+    apply_contrast!(bands)
+  end
+
+  def resolve_home(page)
+    defaults = TEMPLATE_HOME_DEFAULTS[page["template"].to_s] || {}
+    return defaults.dup unless page["home"].is_a?(Hash)
+
+    defaults.merge(page["home"])
+  end
+  private_class_method :resolve_home
+
+  def page_band_meta(page, home)
+    {
+      "key" => page["key"].to_s,
+      "template" => page["template"].to_s,
+      "path" => page["path"].to_s,
+      "title" => page["title"].to_s,
+      "collection" => page["collection"].to_s,
+      "language" => page["language"].to_s,
+      "accent" => page["accent"].to_s,
+      "home" => home
+    }
+  end
+  private_class_method :page_band_meta
+
+  def apply_contrast!(bands)
+    bands.each_with_index do |band, i|
+      # Odd listing bands get contrast; index bands always contrast.
+      band["contrast"] = band["kind"] == "index" || i.odd?
+    end
+    bands
+  end
+  private_class_method :apply_contrast!
+
+  def content_backend(config)
+    raw = config.dig("pandorga", "content", "backend").to_s.strip
+    return "static" if raw.empty?
+
+    raw
+  end
+
+  def content_base_url(config)
+    pandorga_url = config.dig("pandorga", "content", "base_url").to_s.strip
+    return pandorga_url.chomp("/") unless pandorga_url.empty?
+
+    legacy = config["content_api_base_url"].to_s.strip
+    legacy.empty? ? "" : legacy.chomp("/")
+  end
+
+  def object_store_backend?(config)
+    OBJECT_STORE_BACKENDS.include?(content_backend(config))
+  end
+
+  def static_backend?(config)
+    content_backend(config) == "static"
+  end
+end

data/lib/pandorga/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pandorga
+  VERSION = "1.2.1"
+end

data/lib/pandorga.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "pandorga/version"
+
+# Pandorga — Jekyll theme, plugin, and CLI for a static shell with JSON content.
+module Pandorga
+  class Error < StandardError; end
+
+  ROOT = File.expand_path("..", __dir__)
+
+  def self.gem_path(*parts)
+    File.join(ROOT, *parts)
+  end
+end
+
+require_relative "pandorga/registry"
+
+# Jekyll loads this file as a plugin when `plugins: [pandorga]`.
+require_relative "pandorga/jekyll" if defined?(Jekyll)

data/scripts/cdn-allowlist.json

@@ -0,0 +1,19 @@
+{
+  "allowed_urls": [
+    "https://cdn.jsdelivr.net/npm/marked@15.0.7/marked.min.js",
+    "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs",
+    "https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-mml-chtml.js",
+    "https://cdn.jsdelivr.net/npm/d3@7.9.0/dist/d3.min.js",
+    "https://cdn.jsdelivr.net/npm/plotly.js-dist-min@3.1.0/plotly.min.js",
+    "https://cdn.jsdelivr.net/gh/lipis/flag-icons@7.2.3/css/flag-icons.min.css",
+    "https://cdn.tailwindcss.com?plugins=forms,container-queries"
+  ],
+  "scan_globs": [
+    "_layouts",
+    "_includes",
+    "content/media/plots"
+  ],
+  "exceptions": {
+    "tailwind_play_cdn": "Tailwind play CDN cannot be SRI-pinned; URL must match exactly."
+  }
+}

data/scripts/content/backfill-content-keys.rb

@@ -0,0 +1,99 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+require_relative "../../_plugins/content_keys"
+require_relative "../../_plugins/content_detail_paths"
+require_relative "../../_plugins/git_chronology"
+
+REPO_ROOT = Pathname.new(__dir__).join("..", "..").expand_path
+CONTENT_ROOT = REPO_ROOT.join("content")
+
+KEY_OVERRIDES = {
+  "content/collections/posts/2026-03-06-horse-auto-follow.md" => "horse-auto-follow-pt",
+  "content/collections/posts/2026-03-02-mcmc.md" => "mcmc-pt"
+}.freeze
+
+def split_front_matter(text)
+  ContentKeys.split_front_matter(text)
+end
+
+def write_front_matter(path, front_matter, body)
+  yaml = front_matter.to_yaml.sub(/\A---\n/, "").strip
+  path.write("---\n#{yaml}\n---\n\n#{body}")
+end
+
+def infer_key(entry)
+  override = KEY_OVERRIDES[entry["repo_relative_path"]]
+  return override if override
+
+  key = ContentKeys.normalize_key(entry["key"])
+  return key unless key.empty?
+
+  ContentKeys.infer_key_from_filename(entry["path"], entry["type"])
+end
+
+def legacy_detail_path(type, legacy_segment)
+  case type
+  when "article" then ContentDetailPaths.article_detail_path(legacy_segment)
+  when "post" then ContentDetailPaths.post_detail_path(legacy_segment)
+  when "project" then ContentDetailPaths.project_detail_path(legacy_segment)
+  when "product" then ContentDetailPaths.product_detail_path(legacy_segment)
+  else
+    raise "unknown type #{type}"
+  end
+end
+
+def migrate_redirect_fields!(front_matter)
+  redirects = ContentKeys.normalize_redirects(front_matter)
+  front_matter.delete("redirect_from")
+  front_matter["redirects"] = redirects unless redirects.empty?
+  front_matter
+end
+
+def ensure_legacy_redirect!(front_matter, type, legacy_segment, canonical_path)
+  redirects = ContentKeys.normalize_redirects(front_matter)
+  legacy = legacy_detail_path(type, legacy_segment).chomp("/")
+  canonical = canonical_path.chomp("/")
+  redirects << legacy unless legacy == canonical
+  redirects = redirects.map { |path| ContentKeys.normalize_redirect_path(path) }.compact.uniq
+  front_matter["redirects"] = redirects unless redirects.empty?
+  front_matter.delete("redirects") if redirects.empty?
+  front_matter
+end
+
+updated = 0
+ContentKeys::CONTENT_PATHS.each do |type, relative_dir|
+  directory = CONTENT_ROOT.join(relative_dir.sub(%r{\Acontent/}, ""))
+  next unless directory.directory?
+
+  Dir.glob(directory.join("*.{md,markdown}")).sort.each do |absolute_path|
+    entry = ContentKeys.load_entry(absolute_path, type, repo_root: REPO_ROOT)
+    text = File.read(absolute_path).sub(/\A\xEF\xBB\xBF/, "")
+    front_matter, body = split_front_matter(text)
+    original_yaml = front_matter.to_yaml
+
+    key = infer_key(entry)
+    front_matter["key"] = key
+    migrate_redirect_fields!(front_matter)
+
+    if %w[article post].include?(type)
+      GitChronology.apply!(front_matter, entry["repo_relative_path"], type)
+    end
+
+    canonical = ContentKeys.detail_path(type, key, date: front_matter["date"])
+    ensure_legacy_redirect!(front_matter, type, entry["legacy_segment"], canonical)
+
+    next if front_matter.to_yaml == original_yaml
+
+    write_front_matter(Pathname(absolute_path), front_matter, body.sub(/\A\n+/, ""))
+    updated += 1
+    puts "updated #{entry['repo_relative_path']} (key=#{key})"
+  end
+end
+
+ContentKeys.validate!(REPO_ROOT)
+ContentKeys.sync_redirects_file!(REPO_ROOT)
+puts "Backfill complete (#{updated} file(s) updated). Redirects synced to _redirects."