pandorga 1.2.1

data/scripts/pdf/md-to-pdf.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# md-to-pdf.sh — Convert editorial Markdown (article, post, …) to a shareable PDF.
+#
+# Usage:
+#   ./scripts/pdf/md-to-pdf.sh -i <path-to.md> -o <path-to.pdf>
+#
+# Examples:
+#   ./scripts/pdf/md-to-pdf.sh \
+#     -i content/collections/articles/2026-07-17-soft-drones-went-to-war.md \
+#     -o /tmp/soft-drones-went-to-war.pdf
+#
+# Requirements (once):
+#   npm ci --prefix scripts
+#
+# Spec: docs/features/markdown-pdf.md
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+NODE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"   # scripts/ — holds package.json and node_modules
+
+if [ ! -d "$NODE_DIR/node_modules/puppeteer" ] || [ ! -d "$NODE_DIR/node_modules/marked" ] || [ ! -d "$NODE_DIR/node_modules/js-yaml" ]; then
+  echo "==> Installing script Node dependencies..."
+  npm ci --prefix "$NODE_DIR"
+fi
+
+exec node "$SCRIPT_DIR/md-to-pdf.mjs" "$@"

data/scripts/test/fixtures/dual-template/_config.yml

@@ -0,0 +1,32 @@
+title: Dual Template Fixture
+description: Two articles instances with different collections (PLT-AC-4).
+# Minimal Jekyll source for generator unit tests — not a full example site.
+
+pandorga:
+  identity:
+    name: Ada Example
+    short_name: A. Example
+    url: https://example.org
+    locale: en
+  content:
+    backend: static
+    base_url: ""
+  pages:
+    - key: articles-en
+      template: articles
+      title: Articles
+      collection: articles
+      path: /pages/articles/
+      detail: /articles/:slug/
+      language: en
+      nav: { group: Writing, icon: newsmode }
+      home: { featured: true, limit: 3 }
+    - key: articles-notes
+      template: articles
+      title: Notes
+      collection: notes
+      path: /pages/notes/
+      detail: /notes/:slug/
+      language: en
+      nav: { group: Writing, icon: edit_note }
+      home: false

data/scripts/test/fixtures/dual-template/index.html

@@ -0,0 +1,4 @@
+---
+layout: null
+---
+Dual-template fixture (generator only).

data/scripts/test/render-parity/article-note.json

@@ -0,0 +1,5 @@
+{
+  "name": "article-note",
+  "markdown": "<div class=\"article-note\" markdown=\"1\">\nCallout **bold** text.\n</div>",
+  "selectors": ["article-note"]
+}

data/scripts/test/render-parity/blockquote.json

@@ -0,0 +1,5 @@
+{
+  "name": "blockquote",
+  "markdown": "> A quoted line.",
+  "selectors": ["blockquote"]
+}

data/scripts/test/render-parity/blocks/ansi-basic.json

@@ -0,0 +1,7 @@
+{
+  "name": "ansi basic colour",
+  "block": "renderAnsiHtml",
+  "args": ["\\e[31mred\\e[0m plain"],
+  "contains": ["color:var(--ansi-1)", ">red</span>", " plain"],
+  "excludes": ["\\e[", "[31m", "[0m"]
+}

data/scripts/test/render-parity/blocks/ansi-bold-is-bright.json

@@ -0,0 +1,7 @@
+{
+  "name": "ansi bold takes the bright twin",
+  "block": "renderAnsiHtml",
+  "args": ["\\e[1;31mbold red\\e[0m\\e[1mbold default"],
+  "contains": ["color:var(--ansi-9)", "font-weight:700", "color:var(--ansi-fg-bold)"],
+  "excludes": ["color:var(--ansi-1)"]
+}

data/scripts/test/render-parity/blocks/ansi-drops-cursor-moves.json

@@ -0,0 +1,7 @@
+{
+  "name": "ansi drops non-SGR sequences rather than printing them",
+  "block": "renderAnsiHtml",
+  "args": ["\\e[20A\\e[43Cshifted\\e[K"],
+  "contains": ["shifted"],
+  "excludes": ["[20A", "[43C", "[K"]
+}

data/scripts/test/render-parity/blocks/ansi-escapes-markup.json

@@ -0,0 +1,7 @@
+{
+  "name": "ansi capture is escaped, not interpreted",
+  "block": "renderAnsiHtml",
+  "args": ["\\e[32m<script>alert(1)</script> & \"quoted\"\\e[0m"],
+  "contains": ["&lt;script&gt;", "&amp;", "&quot;quoted&quot;"],
+  "excludes": ["<script>"]
+}

data/scripts/test/render-parity/blocks/ansi-extended-colour.json

@@ -0,0 +1,7 @@
+{
+  "name": "ansi 256-colour and truecolour selectors",
+  "block": "renderAnsiHtml",
+  "args": ["\\e[38;5;10mcube\\e[0m\\e[48;5;33mfill\\e[0m\\e[38;2;10;20;30mexact\\e[0m"],
+  "contains": ["color:var(--ansi-10)", "background-color:rgb(0, 135, 255)", "color:rgb(10, 20, 30)"],
+  "excludes": ["38;5", "48;5", "38;2"]
+}

data/scripts/test/render-parity/blocks/ansi-real-control-byte.json

@@ -0,0 +1,7 @@
+{
+  "name": "ansi reads the raw 0x1b byte as well as the printable spelling",
+  "block": "renderAnsiHtml",
+  "args": ["\u001b[36mcyan\u001b[0m"],
+  "contains": ["color:var(--ansi-6)", ">cyan</span>"],
+  "excludes": ["[36m"]
+}

data/scripts/test/render-parity/blocks/archive-card-date-once.json

@@ -0,0 +1,19 @@
+{
+  "name": "archive-card/date-printed-once-by-default",
+  "block": "renderArchiveCard",
+  "args": [
+    {
+      "front_matter": {
+        "title": "Why I chose WSL",
+        "date": "2026-02-24",
+        "last_updated": "2026-08-22",
+        "description": "How a failed dual boot pushed me to WSL2."
+      }
+    },
+    { "href": "/articles/wsl/", "locale": "en", "ctaLabel": "Read article" }
+  ],
+  "selectors": ["div.ledger-meta"],
+  "forbidden": ["date-evolution"],
+  "contains": ["Feb 24, 2026"],
+  "excludes": ["Aug 22, 2026"]
+}

data/scripts/test/render-parity/blocks/archive-card-empty-foot.json

@@ -0,0 +1,7 @@
+{
+  "name": "archive-card/no-cta-no-dates-draws-no-rule",
+  "block": "renderArchiveCard",
+  "args": [{ "slug": "x", "front_matter": { "title": "A title" } }, { "href": "/x/" }],
+  "selectors": ["article.ledger-card", "h3.ledger-card-title"],
+  "excludes": ["ledger-card-foot"]
+}

data/scripts/test/render-parity/blocks/archive-card-footer-dates.json

@@ -0,0 +1,22 @@
+{
+  "name": "archive-card/footer-dates-are-opt-in",
+  "block": "renderArchiveCard",
+  "args": [
+    {
+      "front_matter": {
+        "title": "Why I chose WSL",
+        "date": "2026-02-24",
+        "last_updated": "2026-08-22",
+        "description": "How a failed dual boot pushed me to WSL2."
+      }
+    },
+    {
+      "href": "/articles/wsl/",
+      "locale": "en",
+      "ctaLabel": "Read article",
+      "showFooterDates": true
+    }
+  ],
+  "selectors": ["div.ledger-card-foot", "date-evolution"],
+  "contains": ["Aug 22, 2026"]
+}

data/scripts/test/render-parity/blocks/archive-card-meta-parts.json

@@ -0,0 +1,26 @@
+{
+  "name": "archive-card/metaParts replaces the default strip",
+  "block": "renderArchiveCard",
+  "args": [
+    {
+      "slug": "wsl",
+      "front_matter": {
+        "title": "Why I chose WSL",
+        "date": "2026-02-24",
+        "language": "enus",
+        "tags": ["Engineering"],
+        "description": "How a failed dual boot pushed me to WSL2."
+      }
+    },
+    {
+      "href": "/articles/wsl/",
+      "locale": "en",
+      "ctaLabel": "Read article",
+      "metaParts": ["Feb 24, 2026"]
+    }
+  ],
+  "selectors": ["article.ledger-card", "div.ledger-meta"],
+  "forbidden": ["span.lang-pill"],
+  "contains": ["Feb 24, 2026"],
+  "counts": { "ledger-meta-sep": 0 }
+}

data/scripts/test/render-parity/blocks/archive-card.json

@@ -0,0 +1,32 @@
+{
+  "name": "archive-card/full",
+  "block": "renderArchiveCard",
+  "args": [
+    {
+      "slug": "wsl",
+      "front_matter": {
+        "title": "Why I chose WSL",
+        "date": "2026-02-24",
+        "last_updated": "2026-08-22",
+        "language": "enus",
+        "tags": ["Engineering", "Systems", "Craft"],
+        "description": "How a failed dual boot pushed me to WSL2."
+      }
+    },
+    { "href": "/articles/wsl/", "locale": "en", "ctaLabel": "Read article", "tagLimit": 2 }
+  ],
+  "selectors": [
+    "article.ledger-card",
+    "div.ledger-card-body",
+    "div.ledger-meta",
+    "span.lang-pill",
+    "h3.ledger-card-title",
+    "p.ledger-card-copy",
+    "div.ledger-chip-row",
+    "div.ledger-card-foot",
+    "a.ledger-cta"
+  ],
+  "contains": ["data-dynamic-article=\"true\"", "href=\"/articles/wsl/\"", ">Why I chose WSL<"],
+  "excludes": ["Craft"],
+  "counts": { "ledger-chip": 2, "ledger-meta-sep": 1 }
+}

data/scripts/test/render-parity/blocks/cta-link.json

@@ -0,0 +1,13 @@
+{
+  "name": "cta-link/labelled",
+  "block": "renderCtaLink",
+  "args": ["/articles/deterministic-state/", "Read article", { "className": "home-cta" }],
+  "selectors": ["a.ledger-cta", "span.ledger-cta-arrow"],
+  "contains": [
+    "href=\"/articles/deterministic-state/\"",
+    ">Read article<",
+    ">chevron_right<",
+    "home-cta",
+    "aria-hidden=\"true\""
+  ]
+}

data/scripts/test/render-parity/blocks/lang-pill-pt.json

@@ -0,0 +1,8 @@
+{
+  "name": "lang-pill/portuguese",
+  "block": "renderLangPill",
+  "args": ["ptbr"],
+  "selectors": ["span.lang-pill"],
+  "contains": ["lang-pill--ptbr", "data-language=\"ptbr\"", ">PT<"],
+  "excludes": ["EN"]
+}

data/scripts/test/render-parity/blocks/lang-pill.json

@@ -0,0 +1,8 @@
+{
+  "name": "lang-pill/english",
+  "block": "renderLangPill",
+  "args": ["enus"],
+  "selectors": ["span.lang-pill"],
+  "contains": ["lang-pill--enus", "data-language=\"enus\"", ">EN<"],
+  "excludes": ["PT"]
+}

data/scripts/test/render-parity/blocks/ledger-row-meta-parts.json

@@ -0,0 +1,29 @@
+{
+  "name": "ledger-row/metaParts replaces the default strip",
+  "block": "renderLedgerRow",
+  "args": [
+    {
+      "slug": "wsl",
+      "front_matter": {
+        "title": "Why I chose WSL",
+        "date": "2026-02-24",
+        "language": "enus",
+        "tags": ["Engineering"],
+        "description": "How a failed dual boot pushed me to WSL2."
+      }
+    },
+    {
+      "href": "/articles/wsl/",
+      "locale": "en",
+      "ctaLabel": "Read article",
+      "metaParts": [
+        "Feb 24, 2026",
+        "<span class=\"writing-revised\">Revised Aug 22, 2026</span>"
+      ]
+    }
+  ],
+  "selectors": ["article.ledger-row", "div.ledger-meta", "span.writing-revised"],
+  "forbidden": ["span.lang-pill"],
+  "contains": ["Feb 24, 2026", "Revised Aug 22, 2026"],
+  "counts": { "ledger-meta-sep": 1 }
+}

data/scripts/test/render-parity/blocks/ledger-row.json

@@ -0,0 +1,35 @@
+{
+  "name": "ledger-row/full",
+  "block": "renderLedgerRow",
+  "args": [
+    {
+      "slug": "deterministic-state",
+      "front_matter": {
+        "title": "Deterministic state execution",
+        "date": "2026-01-02",
+        "language": "ptbr",
+        "tags": ["Engineering"],
+        "description": "A note on replaying a state machine from its log."
+      }
+    },
+    { "href": "/posts/deterministic-state/", "locale": "pt-BR", "ctaLabel": "Ler apontamento" }
+  ],
+  "selectors": [
+    "article.ledger-row",
+    "div.ledger-row-head",
+    "div.ledger-meta",
+    "span.lang-pill",
+    "h3.ledger-row-title",
+    "p.ledger-row-copy",
+    "div.ledger-row-foot",
+    "div.ledger-chip-row",
+    "a.ledger-cta"
+  ],
+  "contains": [
+    "href=\"/posts/deterministic-state/\"",
+    ">Deterministic state execution<",
+    ">Ler apontamento<",
+    "A note on replaying a state machine from its log."
+  ],
+  "counts": { "ledger-meta-sep": 1 }
+}

data/scripts/test/render-parity/blocks/meta-strip.json

@@ -0,0 +1,27 @@
+{
+  "name": "meta-strip/two-parts-one-separator",
+  "block": "renderMetaStrip",
+  "args": [
+    [
+      "02 Jan 2026",
+      "<span class=\"lang-pill\">EN</span>"
+    ],
+    {
+      "className": "writing-lead-meta"
+    }
+  ],
+  "selectors": [
+    "div.ledger-meta",
+    "span.ledger-meta-sep"
+  ],
+  "contains": [
+    "writing-lead-meta",
+    "aria-hidden=\"true\""
+  ],
+  "counts": {
+    "ledger-meta-sep": 1
+  },
+  "excludes": [
+    "code-technical"
+  ]
+}

data/scripts/test/render-parity/blocks/poster-media-image.json

@@ -0,0 +1,8 @@
+{
+  "name": "poster-media/image",
+  "block": "renderPosterMedia",
+  "args": ["/media/projects/arco.png", "ARCO"],
+  "selectors": ["div.ledger-poster", "img"],
+  "forbidden": ["video"],
+  "contains": ["loading=\"lazy\"", "decoding=\"async\"", "alt=\"ARCO\"", "onerror="]
+}

data/scripts/test/render-parity/blocks/poster-media-video.json

@@ -0,0 +1,9 @@
+{
+  "name": "poster-media/video-downloads-nothing-until-asked",
+  "block": "renderPosterMedia",
+  "args": ["https://media.example/arco-city-race.mp4", "ARCO city race"],
+  "selectors": ["div.ledger-poster", "video"],
+  "forbidden": ["img"],
+  "contains": ["preload=\"none\"", "controls", "playsinline", "aria-label=\"ARCO city race\""],
+  "excludes": ["autoplay", "loop"]
+}

data/scripts/test/render-parity/blocks/section-banner.json

@@ -0,0 +1,13 @@
+{
+  "name": "section-banner/kicker-title-note",
+  "block": "renderSectionBanner",
+  "args": [{ "kicker": "02", "title": "Long-form inquiries", "note": "12 entries" }],
+  "selectors": [
+    "div.ledger-section-banner",
+    "div.ledger-section-lead",
+    "span.ledger-kicker",
+    "h2.section-title",
+    "span.ledger-section-note"
+  ],
+  "contains": [">02<", ">Long-form inquiries<", ">12 entries<"]
+}

data/scripts/test/render-parity/blocks/system-card-custom-meta.json

@@ -0,0 +1,22 @@
+{
+  "name": "system-card/caller-supplied-meta-parts",
+  "block": "renderSystemCard",
+  "args": [
+    {
+      "front_matter": {
+        "project": "FRET",
+        "label": "Simulation",
+        "status": "Ongoing",
+        "tagline": "Freight routing under stochastic demand."
+      }
+    },
+    {
+      "href": "/projects/fret/",
+      "metaParts": ["<span class=\"ledger-status\">2023 — Ongoing</span>"]
+    }
+  ],
+  "selectors": ["div.ledger-meta", "span.ledger-status"],
+  "contains": ["2023 — Ongoing"],
+  "excludes": [">Simulation<"],
+  "counts": { "ledger-meta-sep": 0, "ledger-status": 1 }
+}

data/scripts/test/render-parity/blocks/system-card.json

@@ -0,0 +1,48 @@
+{
+  "name": "system-card/full",
+  "block": "renderSystemCard",
+  "args": [
+    {
+      "slug": "arco",
+      "front_matter": {
+        "project": "ARCO",
+        "thumbnail": "/media/projects/arco.png",
+        "label": "Simulation",
+        "status": "Ongoing",
+        "tagline": "A city-scale race replayed from telemetry.",
+        "tags": [
+          "Systems"
+        ],
+        "github": "https://github.com/example/arco",
+        "article_url": "/articles/arco/",
+        "external_url": "https://arco.example"
+      }
+    },
+    {
+      "href": "/projects/arco/"
+    }
+  ],
+  "selectors": [
+    "article.ledger-system-card",
+    "div.ledger-poster",
+    "img",
+    "div.ledger-meta",
+    "span.ledger-status",
+    "h3.ledger-card-title",
+    "a.ledger-card-stretch",
+    "p.ledger-card-copy",
+    "div.ledger-chip-row",
+    "div.ledger-card-links"
+  ],
+  "contains": [
+    ">Repository<",
+    ">Article<",
+    ">Visit<",
+    ">ARCO<",
+    ">Simulation"
+  ],
+  "counts": {
+    "ledger-meta-sep": 1,
+    "ledger-cta": 3
+  }
+}

data/scripts/test/render-parity/blocks/tag-chips-links.json

@@ -0,0 +1,12 @@
+{
+  "name": "tag-chips/filter-links-and-limit",
+  "block": "renderTagChips",
+  "args": [
+    ["Engineering", "Systems", "Craft"],
+    { "hrefFor": { "$hrefTemplate": "/pages/articles/?tag={value}" }, "limit": 2 }
+  ],
+  "selectors": ["a.ledger-chip"],
+  "contains": ["href=\"/pages/articles/?tag=Engineering\""],
+  "excludes": ["Craft"],
+  "counts": { "ledger-chip": 2 }
+}

data/scripts/test/render-parity/blocks/tag-chips.json

@@ -0,0 +1,9 @@
+{
+  "name": "tag-chips/static",
+  "block": "renderTagChips",
+  "args": [["Engineering", "Systems"]],
+  "selectors": ["div.ledger-chip-row", "span.ledger-chip"],
+  "forbidden": ["a.ledger-chip"],
+  "contains": [">Engineering<", ">Systems<"],
+  "counts": { "ledger-chip-row": 1, "ledger-chip": 2 }
+}

data/scripts/test/render-parity/cut-in-blank-line.json

@@ -0,0 +1,9 @@
+{
+  "name": "cut-in-blank-line",
+  "markdown": "{% include cut-in.html src=\"/media/images/test.jpg\" alt=\"Test portrait\" %}\n\nFirst wrapping paragraph.\n\nSecond wrapping paragraph.",
+  "selectors": [
+    "figure.article-cut-in-plate",
+    "img.article-cut-in"
+  ],
+  "paragraphCount": 2
+}

data/scripts/test/render-parity/cut-in-right.json

@@ -0,0 +1,9 @@
+{
+  "name": "cut-in-right",
+  "markdown": "{% include cut-in.html src=\"/media/images/test.jpg\" alt=\"Test portrait\" side=\"right\" %}\nFollowing paragraph wraps around the cut-in.",
+  "selectors": [
+    "figure.article-cut-in-plate",
+    "figure.article-cut-in--right",
+    "img.article-cut-in"
+  ]
+}

data/scripts/test/render-parity/cut-in.json

@@ -0,0 +1,8 @@
+{
+  "name": "cut-in",
+  "markdown": "{% include cut-in.html src=\"/media/images/test.jpg\" alt=\"Test portrait\" %}\nFollowing paragraph wraps around the cut-in.",
+  "selectors": [
+    "figure.article-cut-in-plate",
+    "img.article-cut-in"
+  ]
+}

data/scripts/test/render-parity/figure.json

@@ -0,0 +1,5 @@
+{
+  "name": "figure",
+  "markdown": "{% include figure.html src=\"/media/images/test.png\" caption=\"Test caption\" width=\"80\" alt=\"Alt text\" %}",
+  "selectors": ["figure", "img.figure-lightbox-trigger", "figcaption"]
+}