jekyll-theme-zer0 1.20.2 → 1.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2871e1d0cd0522e37b6bac85065edfe6767fc749c39a0ac257fec51dbff97691
-  data.tar.gz: 12d1d870ed1115cd2044446c66b318f4d6e6c65b1ca3a59493353e5a9d6402a9
+  metadata.gz: 9bb7f0d10a0dcb7cbe5297c6a412db670fc837d5acc43c85b6752baab5acf5a9
+  data.tar.gz: '0095e82963f7316a63fecdf355f6fb3e8a126c7528666ab540d274175dda515c'
 SHA512:
-  metadata.gz: 25198dd08404a6ae41724e8e172ce38f832f19b34efd83761cff86ba033c5952e2d315dad70c75b343cb0c94e216c1d5755a0c53048252a2bd7a1c1a61ac590b
-  data.tar.gz: 49d28d829375c95f39986c6e19ff37d524e06f00ae7c388b743e6cd073a35f9c4717aa47f877bb8802d7c5f12fc1f2dd2d618c12785a6342f8a2164774fe6576
+  metadata.gz: 0240ae6516cbc159ae33925ad991e74b958ddbbe19c3806fdf6cde01ba7e625ae6a530184cde8a3e51d5e7748944eba105fec439cde7332910bce2e027f2b5d7
+  data.tar.gz: 80283b4cb1950832efac7b7713f660bab1d106adcc0dbeb320c385570a95cc5fd8e6f88614fd09fabdbc44081369300bc6e4e88ade905125edf5caad4ac14c74

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.22.0](https://github.com/bamr87/zer0-mistakes/compare/v1.21.0...v1.22.0) (2026-06-26)
+
+
+### Features
+
+* **ci:** autonomous CI self-repair loop (pipeline Phase 6) ([#237](https://github.com/bamr87/zer0-mistakes/issues/237)) ([a43db45](https://github.com/bamr87/zer0-mistakes/commit/a43db45eae2da2fcf141ac959d0268dd7e6a52bd))
+* **comments:** enable Giscus + wire Claude Code conversation building ([#214](https://github.com/bamr87/zer0-mistakes/issues/214)) ([fef60a5](https://github.com/bamr87/zer0-mistakes/commit/fef60a5cf78697e94c40f098c336112fe5cdd845))
+* **obsidian:** interactive callouts, parity fixes, a11y + vendored graph ([#200](https://github.com/bamr87/zer0-mistakes/issues/200)) ([affbcd6](https://github.com/bamr87/zer0-mistakes/commit/affbcd62b3f7023457195d5137d5ace2a3751367))
+
+
+### Bug Fixes
+
+* **ci:** enable auto-merge via GraphQL (no git checkout) + graceful no-op ([#232](https://github.com/bamr87/zer0-mistakes/issues/232)) ([4c8c74c](https://github.com/bamr87/zer0-mistakes/commit/4c8c74cfb0775feda9103b379ebcecc4874d517f))
+* **includes:** existence-gate category badge links for remote-theme consumers ([#235](https://github.com/bamr87/zer0-mistakes/issues/235)) ([16ed0a8](https://github.com/bamr87/zer0-mistakes/commit/16ed0a8c77f4cd66b98918a66d00133fa90f4457))
+* **includes:** make component-showcase demo links inert to avoid consumer 404s ([#236](https://github.com/bamr87/zer0-mistakes/issues/236)) ([e96646b](https://github.com/bamr87/zer0-mistakes/commit/e96646b196c2931fc240411ded23184a1e01c8f5))
+* **navigation:** existence-gate the section-sidebar /tags/ links ([#231](https://github.com/bamr87/zer0-mistakes/issues/231)) ([a02b062](https://github.com/bamr87/zer0-mistakes/commit/a02b0622a4f16dfea375629ad347891861283fe3))
+* **search:** degrade search UI gracefully when /search.json is absent ([#234](https://github.com/bamr87/zer0-mistakes/issues/234)) ([f3a718d](https://github.com/bamr87/zer0-mistakes/commit/f3a718d1a9219bee92e2d1a46d2e32c870efb624))
+
+## [1.21.0](https://github.com/bamr87/zer0-mistakes/compare/v1.20.2...v1.21.0) (2026-06-26)
+
+
+### Features
+
+* **automation:** committee planning + specialized executor agents (Phase 4) ([#226](https://github.com/bamr87/zer0-mistakes/issues/226)) ([1e9016b](https://github.com/bamr87/zer0-mistakes/commit/1e9016b869ff33f26fc60d3ae27e7fcd0216e802))
+* **automation:** issue intake + /issue-implement routing (Phases 2-3) ([#225](https://github.com/bamr87/zer0-mistakes/issues/225)) ([21a7008](https://github.com/bamr87/zer0-mistakes/commit/21a70080b2814827bd390201e1ec76fb2b9a874e))
+* **scripts:** issue adoption in sync-backlog (Phase 1) ([#224](https://github.com/bamr87/zer0-mistakes/issues/224)) ([512068e](https://github.com/bamr87/zer0-mistakes/commit/512068e2556be7fe3a4c7870d9feab0ca52955d8))
+
 ## [1.20.2](https://github.com/bamr87/zer0-mistakes/compare/v1.20.1...v1.20.2) (2026-06-25)
 
 

data/_data/backlog.yml

@@ -44,8 +44,15 @@
 #     summary:    1–2 lines of context
 #     acceptance: List of checkable done-criteria the implement routine verifies
 #     links:      { issue: <#|null>, pr: <#|null>, roadmap: "<version>|null" }
+#                 When `issue:` points at an EXISTING issue, sync ADOPTS it (adds
+#                 a managed block, preserves the author's text, no duplicate)
+#                 instead of creating a new one. At most one task per issue.
 #     created:    YYYY-MM-DD
 #     updated:    YYYY-MM-DD
+#     route:      (optional) executor-lane hint for /issue-implement; resolved via
+#                 _data/routing.yml (defaults to the lane for `area`).
+#     depends_on: (optional) [T-NNN, …] tasks that must land first; consumed by the
+#                 /issue-plan committee for ordering. Advisory.
 #
 # `risk: low` + area in {docs, deps, lint} makes a task auto-merge eligible once
 # CI is green (see `.github/prompts/backlog-implement.prompt.md`). Everything
@@ -55,8 +62,8 @@
 
 meta:
   title: "zer0-mistakes Backlog"
-  updated: 2026-06-15
-  next_id: 27
+  updated: 2026-06-26
+  next_id: 32
 
 tasks:
   # --- Housekeeping (seeded so the loop has work on day one) ------------------
@@ -706,3 +713,125 @@ tasks:
     links: { issue: null, pr: null, roadmap: null }
     created: 2026-06-15
     updated: 2026-06-15
+
+  # --- Issue intake 2026-06-26: remote-theme 404 cluster + docs ----------------
+  # Cap: 5 of 7 open issues triaged this run. Deferred (next run): #203 (consumer
+  # checklist docs — companion to T-031); #201 (giscus typo — already in-flight in
+  # PR #214, so no task, to avoid duplicating live work).
+
+  - id: T-027
+    title: "Theme chrome injects unconditional links (/authors/, /news/, /tags/, /posts/, graph) that 404 for remote-theme consumers"
+    status: open
+    priority: P2
+    area: a11y
+    risk: standard
+    effort: M
+    source: issue
+    route: a11y
+    summary: >-
+      Umbrella for the remote-theme 404 class (#204): the theme chrome itself
+      injects internal links to pages whose generators live in `_plugins` (skipped
+      by GitHub Pages safe mode), so a built consumer site has broken links on
+      every page. Guard each link by existence the way the footer "Quick Links"
+      block already does. Specific instances are T-029 (#218 sidebar) and T-030
+      (#219 showcase); T-028 (#202) is the search/sitemap variant. Any fix that
+      edits `_plugins/` is CODEOWNERS-gated -> human review.
+    acceptance:
+      - "Theme-injected chrome links render only when their target exists (mirror the footer Quick-Links existence guard)."
+      - "A link check over a built remote-theme `_site` reports no theme-injected 404s."
+      - "No edit to `lib/jekyll-theme-zer0/version.rb` or release files."
+    links: { issue: 204, pr: null, roadmap: null }
+    created: 2026-06-26
+    updated: 2026-06-26
+
+  - id: T-028
+    title: "remote_theme Pages consumers 404 on /search.json and /sitemap/ (generator is plugin-only)"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: M
+    source: issue
+    route: code-fixer
+    summary: >-
+      On a pure remote-theme Pages consumer, `/search.json` and `/sitemap/` 404
+      because `_plugins/search_and_sitemap_generator.rb` never runs under Pages
+      safe mode (#202). Provide a Pages-safe fallback (committed stubs the navbar
+      search + sitemap link can resolve, or graceful degradation in
+      `assets/js/search-modal.js`). NOTE: editing `_plugins/` is CODEOWNERS-gated
+      -> human review; prefer the non-plugin path.
+    acceptance:
+      - "On a remote-theme Pages build, the navbar search resolves (no /search.json 404) or degrades gracefully."
+      - "The /sitemap/ link resolves (no 404) for a remote-theme consumer."
+      - "No new runtime dependency; no edit to version/release files."
+    links: { issue: 202, pr: null, roadmap: null }
+    created: 2026-06-26
+    updated: 2026-06-26
+
+  - id: T-029
+    title: "Guard the unconditional /tags/ link in section-sidebar.html for remote-theme consumers"
+    status: open
+    priority: P2
+    area: feat
+    risk: low
+    effort: S
+    source: issue
+    route: theme-ui
+    summary: >-
+      `_includes/navigation/section-sidebar.html:69` hardcodes a `/tags/` link;
+      remote-theme consumers have no `/tags/` index (plugin-only), so it 404s
+      (#218). Guard it the way `_includes/core/footer.html` (~138-147) guards its
+      links, or gate on a `site.tags_page` flag. Instance of the T-027 class.
+    acceptance:
+      - "The sidebar 'View All Tags' link renders only when the tags index exists (or a documented site flag is set)."
+      - "Remote-theme consumers no longer 404 from the sidebar link; the Jekyll build stays green."
+      - "A `test/visual/*.spec.js` regression asserts the conditional render (theme-ui / visual-evidence)."
+    links: { issue: 218, pr: null, roadmap: null }
+    created: 2026-06-26
+    updated: 2026-06-26
+
+  - id: T-030
+    title: "component-showcase.html hardcodes demo links (/docs/, /pages/, /docs/customization/) that 404 for consumers"
+    status: open
+    priority: P3
+    area: feat
+    risk: low
+    effort: S
+    source: issue
+    route: theme-ui
+    summary: >-
+      `_includes/components/component-showcase.html` hardcodes absolute demo links
+      (~323-325, 417/421) that 404 for any consumer without those exact routes
+      (#219). Parameterize them (the component already accepts `sections`) or guard
+      each by existence. Low priority — demo component — but it makes the showcase
+      un-includable as-is. Instance of the T-027 class.
+    acceptance:
+      - "The showcase's demo links are parameterized or existence-guarded (no hardcoded absolute paths that can 404)."
+      - "Including the showcase on a consumer site produces no theme-injected 404s; the Jekyll build stays green."
+      - "A `test/visual/*.spec.js` regression covers the parameterized/guarded links (theme-ui / visual-evidence)."
+    links: { issue: 219, pr: null, roadmap: null }
+    created: 2026-06-26
+    updated: 2026-06-26
+
+  - id: T-031
+    title: "Document the safe-mode build-overlay recipe for consumers building outside GitHub Pages"
+    status: open
+    priority: P3
+    area: docs
+    risk: low
+    effort: S
+    source: issue
+    route: content
+    summary: >-
+      Consumers who build the theme outside GitHub Pages (own CI/Actions) must
+      reinvent the safe-mode overlay: clone the remote theme, overlay content,
+      strip `_plugins`, then `jekyll build --strict_front_matter` (#220). Document
+      the recipe in the docs (companion to the #203 consumer checklist). A proven
+      reference exists in lifehacker.dev's `scripts/ci/build.sh`.
+    acceptance:
+      - "A docs page/section under `pages/_docs/` documents the build-overlay recipe (clone -> overlay -> strip _plugins -> strict build)."
+      - "It is cross-linked from the remote-theme/deploy docs and passes markdownlint + the content-review deterministic tier."
+      - "No code change; docs only."
+    links: { issue: 220, pr: null, roadmap: null }
+    created: 2026-06-26
+    updated: 2026-06-26

data/_data/roadmap_plan.yml

@@ -0,0 +1,37 @@
+# =============================================================================
+# Roadmap plan — ORDER-ONLY sequencing artifact
+# =============================================================================
+# Produced by the /issue-plan committee (.github/prompts/issue-plan.prompt.md).
+# Validated + mirrored by scripts/sync-plan.rb.
+#
+# This file sequences OPEN backlog tasks into batches. It is ADVISORY input to
+# the human-dispatched /issue-implement ordering — it does not dispatch anything.
+#
+# HARD INVARIANT (enforced by `sync-plan.rb --check`): order only. A batch may
+# carry ONLY `id`, `goal`, `tasks` (bare T-NNN ids that exist + are open),
+# `depends_on` (other batch ids; the DAG must be acyclic), and `test_framework`.
+# It may NEVER carry risk / priority / area / status / effort / acceptance —
+# those are DERIVED at read-time from `_data/backlog.yml` (the single source of
+# truth), exactly as /backlog-implement already does. Two sources of truth drift.
+#
+# Example batch shape:
+#   batches:
+#     - id: B-1
+#       goal: "Unblock remote-theme consumers"
+#       tasks: [T-027, T-031]
+#       depends_on: []
+#       test_framework: "Playwright smoke for the 404 path + a remote-theme build matrix job"
+#     - id: B-2
+#       goal: "Theme chrome a11y pass"
+#       tasks: [T-033]
+#       depends_on: [B-1]
+#       test_framework: "axe-core checks + before/after visual evidence per the visual-evidence skill"
+# =============================================================================
+
+meta:
+  title: "zer0-mistakes Roadmap Plan"
+  updated: 2026-06-25
+  generated_by: "/issue-plan"
+
+# Populated by the committee. Empty is valid (nothing sequenced yet).
+batches: []

data/_data/routing.yml

@@ -0,0 +1,73 @@
+# =============================================================================
+# Issue routing — area:* (+ optional path globs) → executor lane
+# =============================================================================
+# Used by /issue-implement to pick the specialized executor for a task/issue.
+#
+# Resolution order:
+#   1. explicit task.route -> that lane (override)
+#   2. first `rules` entry whose `area` matches the task's area AND (if it lists
+#      `paths`) a path glob matches a file the work is expected to touch
+#   3. `default` lane
+#
+# A "lane" pairs a specialized .claude/agents/<agent>.md executor with the
+# file-scoped instructions + skills it must load. In v1 (until the cloud-routine
+# substrate spike proves prompt->subagent dispatch), /issue-implement loads the
+# lane's `instructions` + `skills` INLINE and the named `agent` is advisory; once
+# the spike passes it delegates to the agent. Either way the lane is the same.
+#
+# NOTE: this file is DATA. It never grants autonomy — risk/auto-merge eligibility
+# is derived from the backlog task per the autonomy policy in
+# docs/systems/continuous-evolution.md, not from the lane.
+# =============================================================================
+
+default: code-fixer
+
+lanes:
+  content:
+    agent: content-reviewer
+    instructions: [content-review.instructions.md, documentation.instructions.md]
+    skills: [content-review, validate-build]
+    done: "content builds; deterministic + AI content review clean"
+  theme-ui:
+    agent: theme-ui
+    instructions: [layouts.instructions.md, includes.instructions.md, sass.instructions.md, visual-evidence.instructions.md]
+    skills: [change-workflow, visual-evidence, validate-build]
+    done: "jekyll build green; regression spec + before/after evidence committed"
+  code-fixer:
+    agent: code-fixer
+    instructions: [includes.instructions.md, layouts.instructions.md, scripts.instructions.md]
+    skills: [change-workflow, validate-build]
+    done: "targeted tests green; jekyll build green if templates touched"
+  infra-scripts:
+    agent: infra-scripts
+    instructions: [scripts.instructions.md]
+    skills: [change-workflow, validate-build]
+    done: "scripts run; shellcheck/tests green; no CODEOWNERS-owned path touched"
+  test-author:
+    agent: test-author
+    instructions: [testing.instructions.md, visual-evidence.instructions.md]
+    skills: [validate-build]
+    done: "new test fails before the fix and passes after; suite green"
+  a11y:
+    agent: a11y-fixer
+    instructions: [includes.instructions.md, layouts.instructions.md, sass.instructions.md, visual-evidence.instructions.md]
+    skills: [change-workflow, visual-evidence, validate-build]
+    done: "axe/a11y checks pass; regression spec + evidence committed"
+  deps:
+    agent: deps-bumper
+    instructions: []
+    skills: [change-workflow, validate-build]
+    done: "lockfiles consistent; build + tests green"
+
+# First match wins. `feat` appears twice on purpose: a UI-touching feat routes to
+# theme-ui, anything else falls through to the default code-fixer.
+rules:
+  - { area: docs,  lane: content }
+  - { area: a11y,  lane: a11y }
+  - { area: tests, lane: test-author }
+  - { area: infra, lane: infra-scripts }
+  - { area: deps,  lane: deps }
+  - { area: feat,  paths: ["_layouts/**", "_includes/**", "_sass/**", "assets/**"], lane: theme-ui }
+  - { area: feat,  lane: code-fixer }
+  - { area: perf,  lane: code-fixer }
+  - { area: lint,  lane: code-fixer }

data/_includes/components/component-showcase.html

@@ -15,13 +15,21 @@
                         tabs,progress,breadcrumbs,table,tooltips,list-group
                         Default: all sections
 
-  Usage:
-    {% include components/component-showcase.html %}
-    {% include components/component-showcase.html sections="alerts,buttons,cards" %}
+  Usage (wrapped in raw so these examples are shown literally and NOT executed —
+  un-wrapped, Liquid runs them even inside this HTML comment and the include
+  recursively includes itself → "stack level too deep"):
+    {% raw %}{% include components/component-showcase.html %}
+    {% include components/component-showcase.html sections="alerts,buttons,cards" %}{% endraw %}
 
   Dependencies:
   - Bootstrap 5.3 CSS & JS (loaded by theme)
   - Bootstrap Icons (loaded by theme)
+
+  Note: The breadcrumb and list-group links are DEMO links only — they are
+        intentionally inert (href="#" with onclick="return false;") so the
+        showcase never injects site-absolute paths (/docs/, /pages/, ...) that
+        would 404 on consumer sites that lack those exact routes (issue #219).
+        Do not point them at absolute paths.
   ===================================================================
 -->
 {% assign sections = include.sections | default: "alerts,buttons,badges,cards,accordion,tabs,progress,breadcrumbs,table,tooltips,list-group" %}
@@ -320,9 +328,9 @@ theme: jekyll-theme-zer0</code></pre>
 <p>Hierarchical navigation trail showing current page position:</p>
 <nav aria-label="breadcrumb example" class="mb-4">
   <ol class="breadcrumb">
-    <li class="breadcrumb-item"><a href="/" class="text-decoration-none"><i class="bi bi-house me-1"></i>Home</a></li>
-    <li class="breadcrumb-item"><a href="/docs/" class="text-decoration-none">Documentation</a></li>
-    <li class="breadcrumb-item"><a href="/docs/customization/" class="text-decoration-none">Customization</a></li>
+    <li class="breadcrumb-item"><a href="#" class="text-decoration-none" onclick="return false;"><i class="bi bi-house me-1"></i>Home</a></li>
+    <li class="breadcrumb-item"><a href="#" class="text-decoration-none" onclick="return false;">Documentation</a></li>
+    <li class="breadcrumb-item"><a href="#" class="text-decoration-none" onclick="return false;">Customization</a></li>
     <li class="breadcrumb-item active" aria-current="page">Theme Colors</li>
   </ol>
 </nav>
@@ -414,19 +422,19 @@ document.addEventListener('DOMContentLoaded', () => {
 <div class="row g-4 mb-4">
   <div class="col-md-6">
     <div class="list-group">
-      <a href="/pages/" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      <a href="#" onclick="return false;" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
         <span><i class="bi bi-journal-richtext text-primary me-2"></i>Blog Posts</span>
         <span class="badge bg-primary rounded-pill">{{ site.posts.size | default: "12" }}</span>
       </a>
-      <a href="/docs/" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      <a href="#" onclick="return false;" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
         <span><i class="bi bi-book text-success me-2"></i>Documentation</span>
         <span class="badge bg-success rounded-pill">{{ site.documents.size | default: "8" }}</span>
       </a>
-      <a href="/categories/" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      <a href="#" onclick="return false;" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
         <span><i class="bi bi-collection text-info me-2"></i>Categories</span>
         <span class="badge bg-info rounded-pill">{{ site.categories.size | default: "6" }}</span>
       </a>
-      <a href="/tags/" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      <a href="#" onclick="return false;" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
         <span><i class="bi bi-tags text-warning me-2"></i>Tags</span>
         <span class="badge bg-warning text-dark rounded-pill">{{ site.tags.size | default: "24" }}</span>
       </a>

data/_includes/components/js-cdn.html

@@ -44,15 +44,23 @@
 {% endif %}
 
 <!-- Obsidian wiki-link / embed / tag client-side resolver (fallback for the
-     remote_theme GH Pages build, where _plugins/obsidian_links.rb cannot run). -->
+     remote_theme GH Pages build, where _plugins/obsidian_links.rb cannot run).
+     Honours `obsidian: { enabled: false }` in _config.yml — when disabled the
+     resolver script is not loaded and the flag self-disables any fork that
+     loads it another way. Note: `| default: true` would flip `false` back to
+     true (Liquid treats false as falsy), so test enabled == false explicitly. -->
 {%- assign obsidian_attachments_path = site.obsidian.attachments_path | default: '/assets/images/notes' -%}
 <script>
   window.OBSIDIAN_CONFIG = window.OBSIDIAN_CONFIG || {};
+  window.OBSIDIAN_CONFIG.enabled = {% if site.obsidian.enabled == false %}false{% else %}true{% endif %};
   window.OBSIDIAN_CONFIG.wikiIndexUrl = {{ '/assets/data/wiki-index.json' | relative_url | jsonify }};
   window.OBSIDIAN_CONFIG.attachmentsPath = {{ obsidian_attachments_path | relative_url | jsonify }};
   window.OBSIDIAN_CONFIG.tagBase = {{ '/tags/' | relative_url | jsonify }};
+  window.OBSIDIAN_CONFIG.cytoscapeUrl = {{ '/assets/vendor/cytoscape/cytoscape.min.js' | relative_url | jsonify }};
 </script>
-<script defer src="{{ '/assets/js/obsidian-wiki-links.js' | relative_url }}"></script>
+{%- if site.obsidian.enabled != false -%}
+<script defer src="{{ '/assets/js/obsidian-wiki-links.js' | relative_url }}?v={{ site.time | date: '%s' }}"></script>
+{%- endif -%}
 
 <!-- Optional fork overrides: opt-in via `site.user_overrides: true` in _config.yml. -->
 {% if site.user_overrides %}

data/_includes/components/post-card.html

@@ -108,16 +108,30 @@
     <div class="card-body d-flex flex-column">
       
       <!-- Category Badge -->
-      {% comment %} Category base is configurable (`category_base`, default `/news`)
-         to avoid hardcoded 404s for remote-theme consumers. See issue #204. {% endcomment %}
+      {% comment %} Category base is configurable (`category_base`, default `/news`).
+         Only link the badge when that category index page exists in the build;
+         otherwise render a plain badge so remote-theme consumers (whose category
+         section is plugin/page-generated and absent) don't get a 404. Mirrors
+         the tag-badge / footer Quick-Links existence guard. See issue #204. {% endcomment %}
       {% if show_category and include.post.categories.size > 0 %}
         {% assign _category_base = site.category_base | default: '/news' %}
+        {% assign primary_category = include.post.categories | first %}
+        {% capture _category_url %}{{ _category_base }}/{{ primary_category | slugify }}/{% endcapture %}
+        {% comment %} Category index pages can live in site.pages (a regular page) or
+           site.posts (a dated section index), so check both. {% endcomment %}
+        {% assign _category_page = site.html_pages | where: "url", _category_url | first %}
+        {% unless _category_page %}
+          {% assign _category_page = site.posts | where: "url", _category_url | first %}
+        {% endunless %}
         <div class="mb-2">
-          {% assign primary_category = include.post.categories | first %}
-          <a href="{{ site.baseurl }}{{ _category_base }}/{{ primary_category | slugify }}/"
+          {% if _category_page %}
+          <a href="{{ site.baseurl }}{{ _category_url }}"
              class="badge bg-primary text-decoration-none">
             {{ primary_category }}
           </a>
+          {% else %}
+          <span class="badge bg-primary">{{ primary_category }}</span>
+          {% endif %}
         </div>
       {% endif %}
       

data/_includes/content/backlinks.html

@@ -21,11 +21,26 @@
   ===================================================================
 {%- endcomment -%}
 
-{%- if page.backlinks != false -%}
+{%- if page.backlinks != false and site.obsidian.enabled != false -%}
   {%- assign _self_url = page.url -%}
   {%- assign _self_title = page.title | default: "" | downcase | strip -%}
   {%- assign _self_basename = page.path | split: "/" | last | replace: ".md", "" | replace: ".markdown", "" | downcase -%}
 
+  {%- comment -%}
+    Needles = every name another page could wiki-link this page by: title,
+    file basename, and any frontmatter aliases. Normalized to lowercase + strip
+    to match the resolver. A backlink is a [[needle]] with a terminator
+    (]] | # ^) so [[Foobar]] does NOT match the needle "foo".
+  {%- endcomment -%}
+  {%- assign _needles = "" | split: "" -%}
+  {%- if _self_title != "" -%}{%- assign _needles = _needles | push: _self_title -%}{%- endif -%}
+  {%- if _self_basename != "" -%}{%- assign _needles = _needles | push: _self_basename -%}{%- endif -%}
+  {%- for _alias in page.aliases -%}
+    {%- assign _an = _alias | downcase | strip -%}
+    {%- if _an != "" -%}{%- assign _needles = _needles | push: _an -%}{%- endif -%}
+  {%- endfor -%}
+  {%- assign _needles = _needles | uniq -%}
+
   {%- assign _candidates = "" | split: "" -%}
   {%- for _coll in site.collections -%}
     {%- for _doc in _coll.docs -%}
@@ -46,31 +61,44 @@
       {%- if _doc.published == false or _doc.draft == true -%}{%- continue -%}{%- endif -%}
     {%- endunless -%}
     {%- assign _body = _doc.content | default: "" -%}
-    {%- assign _body_lower = _body | downcase -%}
     {%- assign _matched = false -%}
 
+    {%- comment -%} A markdown link to this page's permalink is a backlink. {%- endcomment -%}
     {%- if _self_url and _self_url != "" and _self_url != "/" -%}
       {%- if _body contains _self_url -%}
         {%- assign _matched = true -%}
       {%- endif -%}
     {%- endif -%}
 
+    {%- comment -%}
+      Wiki-link match: strip fenced (```) and inline (`) code first so a page
+      that merely *documents* [[syntax]] doesn't register as a backlink, then
+      require a terminator after the needle.
+    {%- endcomment -%}
     {%- unless _matched -%}
-      {%- if _self_title != "" -%}
-        {%- assign _needle = "[[" | append: _self_title -%}
-        {%- if _body_lower contains _needle -%}
+      {%- assign _nb = "" -%}
+      {%- assign _fp = _body | split: "```" -%}
+      {%- for _p in _fp -%}
+        {%- assign _m = forloop.index0 | modulo: 2 -%}
+        {%- if _m == 0 -%}{%- assign _nb = _nb | append: _p -%}{%- endif -%}
+      {%- endfor -%}
+      {%- assign _nb2 = "" -%}
+      {%- assign _ip = _nb | split: "`" -%}
+      {%- for _p in _ip -%}
+        {%- assign _m = forloop.index0 | modulo: 2 -%}
+        {%- if _m == 0 -%}{%- assign _nb2 = _nb2 | append: _p -%}{%- endif -%}
+      {%- endfor -%}
+      {%- assign _body_lower = _nb2 | downcase -%}
+      {%- for _n in _needles -%}
+        {%- assign _v1 = "[[" | append: _n | append: "]]" -%}
+        {%- assign _v2 = "[[" | append: _n | append: "|" -%}
+        {%- assign _v3 = "[[" | append: _n | append: "#" -%}
+        {%- assign _v4 = "[[" | append: _n | append: "^" -%}
+        {%- if _body_lower contains _v1 or _body_lower contains _v2 or _body_lower contains _v3 or _body_lower contains _v4 -%}
           {%- assign _matched = true -%}
+          {%- break -%}
         {%- endif -%}
-      {%- endif -%}
-    {%- endunless -%}
-
-    {%- unless _matched -%}
-      {%- if _self_basename != "" -%}
-        {%- assign _needle2 = "[[" | append: _self_basename -%}
-        {%- if _body_lower contains _needle2 -%}
-          {%- assign _matched = true -%}
-        {%- endif -%}
-      {%- endif -%}
+      {%- endfor -%}
     {%- endunless -%}
 
     {%- if _matched -%}
@@ -92,11 +120,12 @@
               <strong>{{ _ref.title | default: _ref.path | split: "/" | last }}</strong>
             </a>
             {%- if _ref.collection -%}
-              <span class="badge bg-light text-dark ms-1">{{ _ref.collection }}</span>
+              <span class="badge rounded-pill border text-body-secondary ms-1">{{ _ref.collection }}</span>
             {%- endif -%}
-            {%- if _ref.description -%}
+            {%- assign _ref_excerpt = _ref.description | default: _ref.excerpt | strip_html | strip | truncate: 160 -%}
+            {%- if _ref_excerpt and _ref_excerpt != "" -%}
               <div class="obsidian-backlink-excerpt small text-muted">
-                {{ _ref.description | strip_html | truncate: 160 }}
+                {{ _ref_excerpt }}
               </div>
             {%- endif -%}
           </li>

data/_includes/content/giscus.html

@@ -1,49 +1,35 @@
 <!--
-╔═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
-║                                                giscus.html                                                        ║
-║                                         GitHub Discussions Comment System                                         ║
-╠═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
-║                                                                                                                   ║
-║ Purpose:      Integrates Giscus comment system powered by GitHub Discussions                                     ║
-║ Location:     /_includes/content/giscus.html                                                                     ║
-║ Usage:        include content/giscus.html (Liquid tag; braces omitted — Liquid                                   ║
-║               parses include tags even inside HTML comments, which would error) ║
-║ Dependencies: GitHub repository with Discussions enabled, site.repository, site.giscus configuration           ║
-║                                                                                                                   ║
-║ Features:                                                                                                         ║
-║ • GitHub Discussions-based commenting system                                                                     ║
-║ • Automatic theme detection (preferred_color_scheme)                                                             ║
-║ • Pathname-based mapping for unique comment threads                                                              ║
-║ • Reaction support for enhanced user engagement                                                                  ║
-║ • Top-positioned input for better UX                                                                             ║
-║                                                                                                                   ║
-║ Configuration Options:                                                                                            ║
-║ • data-repo: GitHub repository (site.repository)                                                                 ║
-║ • data-repo-id: GitHub repository ID (site.giscus.data-repo-id)                                                 ║
-║ • data-category-id: Discussions category ID (site.giscus.data-category-id)                                      ║
-║ • data-mapping: "pathname" - maps comments to page URL                                                           ║
-║ • data-strict: "1" - enables strict mapping mode                                                                 ║
-║                                                                                                                   ║
-║ Setup Requirements:                                                                                               ║
-║ • GitHub repository with Discussions feature enabled                                                             ║
-║ • Giscus app installed on the repository                                                                         ║
-║ • Correct repo-id and category-id in _config.yml                                                                 ║
-║                                                                                                                   ║
-║ Reference: Feature Request #FR000001                                                                              ║
-║ Documentation: https://giscus.app/                                                                                ║
-║                                                                                                                   ║
-╚═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
--->
+  giscus.html — GitHub Discussions comment system
+  ===============================================
+
+  Purpose:      Embeds the Giscus widget so page comments are stored as
+                GitHub Discussions (no database, privacy-friendly).
+  Location:     _includes/content/giscus.html
+  Usage:        Rendered by the article / note / notebook layouts, gated on
+                `page.comments != false and site.giscus.enabled`.
+                To include manually elsewhere, use the FULL path:
+                  include content/giscus.html   (wrap in Liquid tags)
+  Dependencies: site.repository, site.giscus.* (see _config.yml), a public
+                repo with Discussions enabled + the Giscus app installed.
+
+  Features:
+  • GitHub Discussions-based commenting
+  • Automatic light/dark theme (preferred_color_scheme)
+  • Pathname-based mapping for one thread per page (data-strict)
+  • Reactions enabled, input positioned at the top
 
-<!-- ===================================================================================================== -->
-<!--                                      GISCUS COMMENT SYSTEM                                           -->
-<!-- ===================================================================================================== -->
-<!-- GitHub Discussions-powered comment system integration                                                -->
-<!-- Feature Request: #FR000001                                                                           -->
-<!-- Documentation: https://giscus.app/                                                                   -->
-<!-- Async loading: Non-blocking comment system initialization                                            -->
+  Config-driven attributes (from _config.yml `giscus:` block):
+  • data-repo        ← site.repository
+  • data-repo-id     ← site.giscus.data-repo-id
+  • data-category-id ← site.giscus.data-category-id
 
-<!-- giscus app - https://giscus.app/ - Feature # FR000001 -->
+  Docs:      pages/_docs/features/giscus-comments.md
+  Reference: https://giscus.app/ (Feature Request #FR000001)
+
+  NOTE: do not write a bare `include giscus.html` example with live Liquid
+  braces inside this file — Liquid evaluates tags even inside HTML comments,
+  which would recursively (and wrongly) try to include "giscus.html".
+-->
 
 <script src="https://giscus.app/client.js"
         data-repo="{{ site.repository }}"
@@ -58,4 +44,4 @@
         data-lang="en"
         crossorigin="anonymous"
         async>
-</script>
+</script>