jekyll-theme-zer0 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 557e14c1256d2eb630827e7136486ff6ecbcd99f77f96b1ca2ae0909c8cbd818
-  data.tar.gz: 9d3dc46191a9085f004b5790110aa9ef24b030b8c830fcc6adc06ed0f3317367
+  metadata.gz: '069f0c330f3b5a4b0fac6331452c7d9d66c5f92308ad9ffef53454e03602efd3'
+  data.tar.gz: 15d1bdacec707645bdc406bab1229253684bf23370f949a7bb6d66b7390aa563
 SHA512:
-  metadata.gz: 9df47e33dbcd2696507527b20a907e081f55f94aa6ad9f1f7dfd517c80549fc87dc96ad0d10d7fa761b1a02b71507465e4c8b130ceb556db54736f1e982449aa
-  data.tar.gz: '039d73f1c388b0c0c1f66f212dcd6abf83a73916690baaecc1127a3c0911da5cb529f841998f68c55a0a280b8468da65bfee6e2d6ac0352d3b97def42ab15e64'
+  metadata.gz: 0c8788ad1dc1ba8af7ca402d5f2643eaab1c47c12307a265d427547b00678ce1115482552aa1090d6d560881282ee70eb6b2674b8bb41e03b9f4d302ce2ba47c
+  data.tar.gz: dc0b3a38a9f1f9d7dfb272ca3c72634845c9bc2295f198b6731e43249f3ecd2a6610a1ddaf92cb20457443c71e337b4ced9352fe85d41eb641604e12d2eba426

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.3.0] - 2026-04-24
+
+### Changed
+- Version bump: minor release
+
+### Commits in this release
+- 31e042c feat: Obsidian vault integration with client-side wiki-link resolver and backlinks (#73)
+
+
+## [1.2.1] - 2026-04-22
+
+### Changed
+- Version bump: patch release
+
+### Commits in this release
+- 5c04e62 fix(footer,welcome,info): eliminate broken links on bare-minimum sites
+
+
 ## [1.2.0] - 2026-04-22
 
 ### Changed
@@ -22,6 +40,27 @@
 ## [Unreleased]
 
 ### Added
+- **Obsidian Integration** — The repo's markdown content is now editable as an [Obsidian](https://obsidian.md) vault and rendered identically on GitHub Pages.
+  - Shared vault config (`.obsidian/app.json`, `core-plugins.json`, `community-plugins.json`, `appearance.json`, `hotkeys.json`, `templates.json`) and a Templates-compatible note template at `pages/_notes/_templates/note-template.md`.
+  - Liquid-generated `assets/data/wiki-index.json` listing every collection document and standalone page (title, basename, permalink, tags, aliases, excerpt) — works on the default GitHub Pages remote_theme build, no plugin whitelist changes required.
+  - `assets/js/obsidian-wiki-links.js` — client-side resolver that rewrites `[[wiki-links]]` (with aliases, header anchors, broken-link styling), `![[embeds]]` (image with width modifiers, note transclusion), inline `#tags`, and Obsidian callout blockquotes (`> [!note] Title …`) into Bootstrap-styled HTML.
+  - `_includes/content/backlinks.html` — server-side backlinks panel auto-rendered on every `note` layout (and on any page with `backlinks: true`); fully indexable by search engines.
+  - `_includes/content/transclude.html` — note embed renderer used by both the JS resolver and the Ruby converter.
+  - `_sass/core/_obsidian.scss` (imported via `_sass/custom.scss`) — styles for wiki-links, broken links, callouts, embeds, and the backlinks panel.
+  - `_plugins/obsidian_links.rb` — opt-in Ruby converter that performs the same transformations server-side for forks that build with vanilla Jekyll (without the `github-pages` gem) or use a custom GH Actions workflow that bypasses the plugin whitelist.
+  - `pages/_docs/obsidian/` — full documentation section: index, getting started, syntax reference, authoring workflow, troubleshooting.
+  - `_config.yml` — added `*.canvas` and `*.excalidraw.md` to `exclude:`; `jekyll-redirect-from` enabled to map Obsidian `aliases:` to URL redirects.
+  - `.gitignore` — ignore Obsidian's local-only state (`workspace*`, `cache`, `plugins/*/data.json`, `graph.json`, `.trash/`).
+- **Tests**:
+  - `test/test_ruby_converter.rb` — 18-test, 65-assertion Minitest suite for `_plugins/obsidian_links.rb` covering wiki-links, embeds, callouts (including fold markers and unknown-type fallback), inline tags, code-block isolation, and a plain-markdown regression guard.
+  - `test/test_resolver.js` — 16-assertion Node test for `assets/js/obsidian-wiki-links.js` using a hand-rolled DOM shim; exercises wiki-link resolution, embeds, tags, and DOM-level callout rewriting.
+  - `test/test_obsidian.sh` — orchestrator that runs both unit suites and validates that the Jekyll build emits a well-formed `wiki-index.json`. Wired into `test/test_runner.sh`.
+  - `test/fixtures/obsidian/sample-note.md` — representative Obsidian note exercising every supported feature.
+- **Obsidian Graph View** — Live, force-directed knowledge graph at `/docs/obsidian/graph/` mirroring Obsidian's local graph view. Built from the same `assets/data/wiki-index.json` that powers the resolver and backlinks panel.
+  - `pages/_docs/obsidian/graph.md` — graph page (Bootstrap toolbar with title filter, "Show orphans" switch, "Reset view" button; collection-color legend; usage tips). Cytoscape.js loaded only on this page via CDN with SRI + `crossorigin="anonymous"`.
+  - `assets/js/obsidian-graph.js` — vanilla-JS renderer (~330 lines, no build step). Mirrors the resolver's normalization (`toLowerCase().trim()` + whitespace collapse) so wiki-index keys match. `cose` force layout, hover-highlight neighborhood, click-to-navigate (⌘/Ctrl-click for new tab), search-driven node fading, orphans hidden by default with a Bootstrap switch toggle. Broken targets render as dashed red nodes prefixed `__broken__:` in the graph model.
+  - `assets/data/wiki-index.json` — extended each entry with an `outgoing: [...]` array of normalized wiki-link targets, extracted at build time via Liquid (masks `![[…]]` embeds, splits on `[[`/`]]`/`|`/`#`/`^`, downcases, dedupes).
+- **Docs**: `README.md` and `AGENTS.md` updated with an Obsidian vault section pointing to the new docs.
 - **Bare-minimum 3-file remote-theme starter.** Consumers can now publish a
   fully styled site to GitHub Pages with only `_config.yml`, `Gemfile`, and
   `index.md` — no installer required. The new `_layouts/welcome.html` shipped
@@ -37,6 +76,37 @@
   `Your Site Title`, `My Awesome Site`, `Welcome`, `Untitled`, or empty).
 
 ### Fixed
+- **Footer Quick Links no longer 404 on bare-minimum sites.**
+  `_includes/core/footer.html` previously hard-coded links to
+  `/about/`, `/services/`, `/news/`, `/contact/`, `/privacy-policy`, and
+  `/terms-of-service` — none of which exist in a 3-file remote-theme
+  consumer. Quick Links are now resolved in this order:
+  1. `site.footer_quick_links` (array of `{label, url}`) — explicit override
+  2. Auto-detection: each candidate link only renders if the target page
+     exists in `site.html_pages`
+  3. Fallback to `Home` + `Sitemap (XML)` only.
+  Privacy Policy / Terms of Service links use the same existence check and
+  optionally read from `site.privacy_policy_url` / `site.terms_of_service_url`.
+- **Welcome layout external links now point to existing README anchors.**
+  The "Next steps" cards in `_layouts/welcome.html` linked to
+  `#content-creation` and `#customisation`, which don't exist in the theme
+  README. They now point to `README.md#-quick-start` and
+  `README.md#-key-features` respectively.
+- **Theme info admin links are conditional.**
+  `_includes/components/info-section.html` previously rendered Admin
+  Dashboard links to `/about/config/`, `/about/settings/theme/`,
+  `/about/settings/navigation/`, and `/about/settings/environment/`
+  unconditionally — guaranteed 404s on bare-minimum sites. The links and
+  surrounding section now only render when the corresponding page exists.
+- **Source Code shortcuts skip GitHub buttons when repository is unknown.**
+  `_includes/components/dev-shortcuts.html` rendered `https://github.com//blob//`
+  URLs when `site.repository` and `site.branch` were empty (typical on bare
+  consumer sites). It now hides the GitHub-based buttons and shows a hint
+  to set `repository: USER/REPO` in `_config.yml`.
+- **Cookie-consent privacy link is conditional.** The "Learn more in our
+  Privacy Policy" anchor in `_includes/components/cookie-consent.html` only
+  renders if a `/privacy-policy/` page exists or `site.privacy_policy_url` is
+  configured.
 - **Setup banner link.** `_includes/components/setup-banner.html` no longer
   points at the non-existent `/404.html`; it now links to
   `/#setup-wizard`, which is provided by the new welcome layout.
@@ -139,10 +209,18 @@ See [`docs/installation/migration-from-0.x.md`](docs/installation/migration-from
 - **Roadmap data file**: `_data/roadmap.yml` is now the single source of truth for the project roadmap (versions, status, dates, targets, and feature highlights).
 - **Roadmap generator**: `scripts/generate-roadmap.rb` (and shell wrapper `scripts/generate-roadmap.sh`) renders a Mermaid gantt diagram and summary table from `_data/roadmap.yml` and injects them into `README.md` between `<!-- ROADMAP_MERMAID:START/END -->` and `<!-- ROADMAP_TABLE:START/END -->` markers. Supports `--check` mode for CI drift detection and `--stdout` for previewing.
 - **Roadmap sync workflow**: `.github/workflows/roadmap-sync.yml` regenerates the README on push to `main` when the data file or generator changes, and verifies sync on PRs that touch those files.
+- **Local Graph Sidebar Widget** — Per-page mini Obsidian-style local graph rendered at the top of the left sidebar on every page that has one.
+  - `_includes/navigation/local-graph.html` — small widget with a "Local graph" heading, a "full ›" link to `/docs/obsidian/graph/`, and a `#obsidian-local-graph` container. Honors `local_graph: false` and `local_graph_depth: N` (default 1) in page front matter.
+  - `assets/js/obsidian-local-graph.js` — fetches `wiki-index.json`, finds the current page by `window.location.pathname` (with title/basename fallback), BFS through both outgoing and incoming wiki-links to the configured depth, renders the subgraph with cytoscape.js (`cose` layout sized for ~220px sidebar canvas). Highlights the current page with an orange border + larger node + bold label. Click navigates (⌘/Ctrl-click opens new tab). Hides itself silently if the page isn't in the wiki-index or has no neighbors. Cytoscape is lazy-loaded from CDN with SRI + `crossorigin="anonymous"` and de-duplicated against the full graph page's existing load.
+  - `_includes/navigation/sidebar-left.html` — includes the new widget at the top of `.offcanvas-body`, before the nav-mode chain.
+  - `_sass/core/_obsidian.scss` — added `.obsidian-local-graph-widget` styles for the 220px container with theme-aware borders/background.
 - **Docs**: `docs/FORKING.md` — progressive fork → configure → personalize workflow for the `username.github.io` user-site pattern
 - **Tests**: `test/test_fork_cleanup.sh` — 32-assertion suite covering CLI parsing, dry-run, real cleanup, YAML anchor preservation, and idempotency
 
 ### Changed
+- **Obsidian docs**: `pages/_docs/obsidian/syntax-reference.md` — graph view now marked **Available** (was "Not yet implemented"); `pages/_docs/obsidian/index.md` — added Graph view row to the section table.
+- **Documentation cross-linking**: appended a `## See also` block of `[[wiki-links]]` to every page in `pages/_docs/` (76 files — section indexes, leaf pages, and the obsidian cluster) so the graph view shows real cluster structure. Edge count grew from 12 → 292 with 90+ visible nodes after orphan filtering.
+- **Obsidian Graph View polish**: removed the white pill backgrounds behind labels (now halo-only outlines that match the canvas color, so edges read through cleanly); labels hide by default and reveal on zoom-in or hover, while the 37 hub nodes (degree ≥ 6 — Docker, Front Matter, Jeykll, Layouts, Customization, Release Management, etc.) keep their labels always-on as landmarks; loosened `cose` layout (`nodeRepulsion` 8000→18000, `idealEdgeLength` 80→130, added `nodeOverlap: 24` and `componentSpacing: 80`, dropped gravity 0.25→0.18, `numIter` 2500); taller canvas (`82vh` / `620px` min, was `75vh` / `520px`); bigger `cy.fit()` padding (40→70 default, 80→100 for search matches) so top-row labels don't clip the canvas edge.
 - **README roadmap section** is now auto-generated from `_data/roadmap.yml` instead of being hand-maintained, and includes status, target, and detailed highlight columns.
 - **`pages/roadmap.md`** rewritten to render the Mermaid gantt chart, release summary, and per-version detail sections directly from `_data/roadmap.yml` via Liquid — so the Jekyll page is always live with the canonical data.
 - **`_data/README.md`** documents the new `roadmap.yml` data file.

data/README.md

@@ -2,7 +2,7 @@
 title: zer0-mistakes
 sub-title: AI-Native Jekyll Theme
 description: AI-native Jekyll theme for GitHub Pages — Docker-first development, AI-powered installation, multi-agent integration (Copilot, Codex, Cursor, Claude), AI preview-image generation, and AIEO content optimization with Bootstrap 5.3.
-version: 1.2.0
+version: 1.3.0
 layout: landing
 tags:
   - jekyll
@@ -20,7 +20,7 @@ categories:
   - bootstrap
   - ai-tooling
 created: 2024-02-10T23:51:11.480Z
-lastmod: 2026-04-22T02:41:59.000Z
+lastmod: 2026-04-24T23:27:06.000Z
 draft: false
 permalink: /
 slug: zer0
@@ -473,6 +473,30 @@ stateDiagram-v2
 | Pie | `pie` | Distributions |
 | Git | `gitGraph` | Branch history |
 
+### 🧠 Obsidian Vault Integration
+
+Edit your content as an [Obsidian](https://obsidian.md) vault — same files,
+same git history, identical rendering on the published site:
+
+- **Open repo as a vault**: shared `.obsidian/` config commits with the repo.
+- **Wiki-links** `[[Page Title]]` and aliases `[[Page|Alias]]` resolve to permalinks.
+- **Embeds**: `![[image.png|400]]` for images, `![[Note Title]]` for note transclusion.
+- **Callouts** `> [!note] …` map to Bootstrap alert components.
+- **Backlinks panel** auto-renders on every note (and on any page with `backlinks: true`).
+- **Inline tags** `#topic` link to the tag index, hierarchical tags supported.
+- **Zero plugin requirements**: works on the default GitHub Pages
+  `remote_theme` build via a client-side resolver
+  (`assets/js/obsidian-wiki-links.js`) backed by a Liquid-generated
+  `assets/data/wiki-index.json`.
+
+```bash
+# Open the repo root as an Obsidian vault, edit, then commit & push
+git commit -am "note: today's thinking" && git push
+```
+
+Read the [Obsidian docs](pages/_docs/obsidian/) for setup, syntax reference,
+authoring workflow, and troubleshooting.
+
 ### 📓 Jupyter Notebook Support
 
 Seamless integration for data science and computational content:
@@ -1114,7 +1138,7 @@ git push origin feature/awesome-feature
 
 | Metric | Value |
 |--------|-------|
-| **Current Version** | 1.2.0 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
+| **Current Version** | 1.3.0 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
 | **Documented Features** | 43 ([Feature Registry](https://github.com/bamr87/zer0-mistakes/blob/main/_data/features.yml)) |
 | **Setup Time** | 2-5 minutes ([install.sh benchmarks](https://github.com/bamr87/zer0-mistakes/blob/main/install.sh)) |
 | **Documentation Pages** | 70+ ([browse docs](/pages/)) |
@@ -1165,6 +1189,6 @@ And these AI partners that make zer0-mistakes truly AI-native:
 
 **Built with ❤️ — and a little help from our AI partners — for the Jekyll community**
 
-**v1.2.0** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
+**v1.3.0** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
 
 

data/_includes/components/cookie-consent.html

@@ -59,7 +59,11 @@ Configuration: Uses site.posthog settings from _config.yml
         </p>
         <p class="mb-2 mb-lg-0 small text-white-50">
           This website uses cookies and similar technologies to enhance your browsing experience, analyze traffic, and provide personalized content.
-          <a href="{{ '/privacy-policy/' | relative_url }}" class="text-white text-decoration-underline">Learn more in our Privacy Policy</a>.
+          {% assign _pp = site.html_pages | where: "url", "/privacy-policy/" | first %}
+          {% unless _pp %}{% assign _pp = site.html_pages | where: "url", "/privacy-policy" | first %}{% endunless %}
+          {% if _pp or site.privacy_policy_url %}
+            <a href="{{ site.privacy_policy_url | default: '/privacy-policy/' | relative_url }}" class="text-white text-decoration-underline">Learn more in our Privacy Policy</a>.
+          {% endif %}
         </p>
       </div>
       <div class="col-12 col-lg-4">

data/_includes/components/dev-shortcuts.html

@@ -33,6 +33,11 @@
 <div class="dev-shortcuts">
   <div class="d-flex flex-column gap-2">
 
+    {% comment %} Skip all GitHub-based shortcuts on bare/unconfigured sites where
+       site.repository or site.branch are empty (otherwise we render
+       https://github.com//blob//path → 404). {% endcomment %}
+    {% if site.repository and site.branch %}
+
     <!-- Button Group (section title is the parent h6 in info-section.html) -->
     <div class="btn-group-vertical" role="group" aria-label="Source code shortcuts">
 
@@ -109,5 +114,13 @@
 
     </div>
 
+    {% else %}
+      <p class="small text-body-secondary mb-0">
+        <i class="bi bi-info-circle me-1"></i>
+        Set <code>repository: USER/REPO</code> in your <code>_config.yml</code>
+        to enable source-code shortcuts.
+      </p>
+    {% endif %}
+
   </div>
 </div>

data/_includes/components/info-section.html

@@ -108,35 +108,51 @@
           </div>
         </div>
 
-        <!-- Admin Quick Links -->
+        <!-- Admin Quick Links — only render links to pages that actually exist
+             in the build (prevents 404s on bare-minimum / remote-theme sites
+             that haven't created the admin pages). -->
+        {% assign _cfg_page = site.html_pages | where: "url", "/about/config/" | first %}
+        {% assign _theme_page = site.html_pages | where: "url", "/about/settings/theme/" | first %}
+        {% assign _nav_page = site.html_pages | where: "url", "/about/settings/navigation/" | first %}
+        {% if _cfg_page or _theme_page or _nav_page %}
         <div class="mb-3">
           <h6 class="text-body-secondary small text-uppercase fw-semibold mb-2">
             <i class="bi bi-speedometer2 me-1"></i>Admin Dashboard
           </h6>
           <div class="list-group list-group-flush small">
+            {% if _cfg_page %}
             <a href="{{ '/about/config/' | relative_url }}" class="list-group-item list-group-item-action d-flex align-items-center px-0">
               <i class="bi bi-gear me-2 text-body-secondary"></i>Configuration
             </a>
+            {% endif %}
+            {% if _theme_page %}
             <a href="{{ '/about/settings/theme/' | relative_url }}" class="list-group-item list-group-item-action d-flex align-items-center px-0">
               <i class="bi bi-palette me-2 text-body-secondary"></i>Theme Customizer
             </a>
+            {% endif %}
+            {% if _nav_page %}
             <a href="{{ '/about/settings/navigation/' | relative_url }}" class="list-group-item list-group-item-action d-flex align-items-center px-0">
               <i class="bi bi-signpost-2 me-2 text-body-secondary"></i>Navigation Editor
             </a>
+            {% endif %}
           </div>
         </div>
+        {% endif %}
       </div>
       
       <!-- Environment Tab -->
       <div class="tab-pane fade" id="environment-pane" role="tabpanel" aria-labelledby="environment-tab" tabindex="0">
         {% include components/env-switcher.html %}
 
-        <!-- Admin Link -->
+        <!-- Admin Link — only when target page exists -->
+        {% assign _env_page = site.html_pages | where: "url", "/about/settings/environment/" | first %}
+        {% if _env_page %}
         <div class="mt-4 pt-3 border-top">
           <a href="{{ '/about/settings/environment/' | relative_url }}" class="btn btn-outline-secondary btn-sm w-100">
             <i class="bi bi-box-arrow-up-right me-1"></i>Full Environment &amp; Build Info
           </a>
         </div>
+        {% endif %}
       </div>
       
       <!-- Developer Tab -->

data/_includes/components/js-cdn.html

@@ -31,4 +31,8 @@
 <script src="{{ '/assets/js/search-modal.js' | relative_url }}"></script>
 
 <!-- fffuel-style background customizer (skin switching, toggle, opacity) -->
-<script src="{{ '/assets/js/background-customizer.js' | relative_url }}"></script>
+<script src="{{ '/assets/js/background-customizer.js' | relative_url }}"></script>
+
+<!-- Obsidian wiki-link / embed / tag client-side resolver (fallback for the
+     remote_theme GH Pages build, where _plugins/obsidian_links.rb cannot run). -->
+<script defer src="{{ '/assets/js/obsidian-wiki-links.js' | relative_url }}"></script>

data/_includes/content/backlinks.html

@@ -0,0 +1,103 @@
+{%- comment -%}
+  ===================================================================
+  BACKLINKS — Pages that wiki-link or markdown-link to the current page
+  ===================================================================
+
+  File: backlinks.html
+  Path: _includes/content/backlinks.html
+  Purpose: Render an Obsidian-style "Linked mentions" panel.
+
+  Strategy:
+    - Iterate every collection document + standalone page.
+    - Match either the current page's permalink in the body, or its title /
+      basename inside `[[…]]` wiki-link syntax (case-insensitive, whitespace
+      collapsed — same normalization as _plugins/obsidian_links.rb).
+    - Skip self-references and drafts.
+
+  Toggle:
+    - Set `backlinks: false` in front matter to suppress.
+    - Default: ON for `_layouts/note.html`, OFF for `_layouts/default.html`
+      (opt-in via `backlinks: true`).
+  ===================================================================
+{%- endcomment -%}
+
+{%- if page.backlinks != 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 -%}
+
+  {%- assign _candidates = "" | split: "" -%}
+  {%- for _coll in site.collections -%}
+    {%- for _doc in _coll.docs -%}
+      {%- assign _candidates = _candidates | push: _doc -%}
+    {%- endfor -%}
+  {%- endfor -%}
+  {%- for _pg in site.pages -%}
+    {%- if _pg.output_ext == ".html" -%}
+      {%- assign _candidates = _candidates | push: _pg -%}
+    {%- endif -%}
+  {%- endfor -%}
+
+  {%- assign _backlinks = "" | split: "" -%}
+  {%- for _doc in _candidates -%}
+    {%- if _doc.url == _self_url -%}{%- continue -%}{%- endif -%}
+    {%- assign _body = _doc.content | default: "" -%}
+    {%- assign _body_lower = _body | downcase -%}
+    {%- assign _matched = false -%}
+
+    {%- if _self_url and _self_url != "" and _self_url != "/" -%}
+      {%- if _body contains _self_url -%}
+        {%- assign _matched = true -%}
+      {%- endif -%}
+    {%- endif -%}
+
+    {%- unless _matched -%}
+      {%- if _self_title != "" -%}
+        {%- assign _needle = "[[" | append: _self_title -%}
+        {%- if _body_lower contains _needle -%}
+          {%- assign _matched = true -%}
+        {%- endif -%}
+      {%- endif -%}
+    {%- endunless -%}
+
+    {%- unless _matched -%}
+      {%- if _self_basename != "" -%}
+        {%- assign _needle2 = "[[" | append: _self_basename -%}
+        {%- if _body_lower contains _needle2 -%}
+          {%- assign _matched = true -%}
+        {%- endif -%}
+      {%- endif -%}
+    {%- endunless -%}
+
+    {%- if _matched -%}
+      {%- assign _backlinks = _backlinks | push: _doc -%}
+    {%- endif -%}
+  {%- endfor -%}
+
+  {%- if _backlinks.size > 0 -%}
+    <section class="obsidian-backlinks mt-5 pt-4 border-top" aria-labelledby="backlinks-heading">
+      <h3 id="backlinks-heading" class="h5 mb-3">
+        <i class="bi bi-link-45deg me-1" aria-hidden="true"></i>
+        Linked mentions
+        <span class="badge bg-secondary ms-2">{{ _backlinks.size }}</span>
+      </h3>
+      <ul class="list-unstyled obsidian-backlinks-list">
+        {%- for _ref in _backlinks -%}
+          <li class="obsidian-backlink mb-2">
+            <a href="{{ _ref.url | relative_url }}" class="obsidian-backlink-link">
+              <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>
+            {%- endif -%}
+            {%- if _ref.description -%}
+              <div class="obsidian-backlink-excerpt small text-muted">
+                {{ _ref.description | strip_html | truncate: 160 }}
+              </div>
+            {%- endif -%}
+          </li>
+        {%- endfor -%}
+      </ul>
+    </section>
+  {%- endif -%}
+{%- endif -%}

data/_includes/content/transclude.html

@@ -0,0 +1,62 @@
+{%- comment -%}
+  ===================================================================
+  TRANSCLUDE — Inline render of an embedded note (![[Note Title]])
+  ===================================================================
+
+  File: transclude.html
+  Path: _includes/content/transclude.html
+  Purpose: Render the body of another collection document inline.
+
+  Parameters:
+    - target (required): canonical title or basename of the embedded note
+    - url (required): resolved permalink (provided by _plugins/obsidian_links.rb)
+
+  Used by:
+    - _plugins/obsidian_links.rb (Ruby converter for `![[Note Title]]`)
+
+  Notes:
+    - We deliberately do NOT recursively run the Obsidian converter on the
+      embedded body to avoid transclusion loops.
+    - Falls back to a "broken embed" alert if the URL doesn't resolve to a
+      known site.documents entry.
+  ===================================================================
+{%- endcomment -%}
+
+{%- assign _embed_target = include.target -%}
+{%- assign _embed_url = include.url | split: "#" | first -%}
+{%- assign _embedded = nil -%}
+{%- for _doc in site.documents -%}
+  {%- if _doc.url == _embed_url -%}
+    {%- assign _embedded = _doc -%}
+    {%- break -%}
+  {%- endif -%}
+{%- endfor -%}
+{%- if _embedded == nil -%}
+  {%- for _page in site.pages -%}
+    {%- if _page.url == _embed_url -%}
+      {%- assign _embedded = _page -%}
+      {%- break -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+
+{% if _embedded %}
+<aside class="obsidian-embed obsidian-embed-note card my-3" aria-label="Embedded note: {{ _embedded.title | default: _embed_target }}">
+  <div class="card-header d-flex justify-content-between align-items-center">
+    <span class="obsidian-embed-source">
+      <i class="bi bi-link-45deg me-1" aria-hidden="true"></i>
+      Embedded: <a href="{{ include.url | relative_url }}">{{ _embedded.title | default: _embed_target }}</a>
+    </span>
+    {% if _embedded.date %}
+      <small class="text-muted">{{ _embedded.date | date: "%Y-%m-%d" }}</small>
+    {% endif %}
+  </div>
+  <div class="card-body obsidian-embed-body">
+    {{ _embedded.content | strip_html | truncate: 800 | markdownify }}
+  </div>
+</aside>
+{% else %}
+<div class="obsidian-embed obsidian-embed-broken alert alert-warning" role="alert">
+  Embed not found: <code>{{ _embed_target | escape }}</code>
+</div>
+{% endif %}

data/_includes/core/footer.html

@@ -80,16 +80,33 @@
             {% if site.email %}<p class="mb-0"><a href="mailto:{{ site.email }}" class="text-light text-decoration-none">{{ site.email }}</a></p>{% endif %}
           </div>
 
-          <!-- Quick Links -->
+          <!-- Quick Links
+               Resolution order:
+                 1. site.footer_quick_links  (array of {label, url}) — explicit override
+                 2. Auto-detection: only render links whose target pages
+                    actually exist in the build. Prevents 404s on bare-minimum
+                    sites that haven't created /about/, /services/, etc. -->
           <div class="col-12 col-md-6 col-lg-3 mb-3">
             <h5 class="text-uppercase mb-3">Quick Links</h5>
             <ul class="list-unstyled" aria-label="Footer quick links">
-              <li><a href="{{ '/' | relative_url }}" class="text-light text-decoration-none">Home</a></li>
-              <li><a href="{{ '/about/' | relative_url }}" class="text-light text-decoration-none">About</a></li>
-              <li><a href="{{ '/services/' | relative_url }}" class="text-light text-decoration-none">Services</a></li>
-              <li><a href="{{ '/news/' | relative_url }}" class="text-light text-decoration-none">News</a></li>
-              <li><a href="{{ '/contact/' | relative_url }}" class="text-light text-decoration-none">Contact</a></li>
-              <li><a href="{{ '/sitemap.xml' | relative_url }}" class="text-light text-decoration-none">Sitemap (XML)</a></li>
+              {% if site.footer_quick_links %}
+                {% for link in site.footer_quick_links %}
+                  <li><a href="{{ link.url | relative_url }}" class="text-light text-decoration-none">{{ link.label }}</a></li>
+                {% endfor %}
+              {% else %}
+                <li><a href="{{ '/' | relative_url }}" class="text-light text-decoration-none">Home</a></li>
+                {% assign _candidate_links = "About,/about/|Services,/services/|News,/news/|Contact,/contact/" | split: "|" %}
+                {% for entry in _candidate_links %}
+                  {% assign _parts = entry | split: "," %}
+                  {% assign _label = _parts[0] %}
+                  {% assign _url   = _parts[1] %}
+                  {% assign _page  = site.html_pages | where: "url", _url | first %}
+                  {% if _page %}
+                    <li><a href="{{ _url | relative_url }}" class="text-light text-decoration-none">{{ _label }}</a></li>
+                  {% endif %}
+                {% endfor %}
+                <li><a href="{{ '/sitemap.xml' | relative_url }}" class="text-light text-decoration-none">Sitemap (XML)</a></li>
+              {% endif %}
             </ul>
           </div>
 
@@ -151,8 +168,17 @@
           </div>
           <div class="col-md-4 text-md-end">
             <ul class="list-inline mb-0">
-              <li class="list-inline-item"><a href="{{ '/privacy-policy' | relative_url }}" class="text-light text-decoration-none">Privacy Policy</a></li>
-              <li class="list-inline-item"><a href="{{ '/terms-of-service' | relative_url }}" class="text-light text-decoration-none">Terms of Service</a></li>
+              {% comment %} Only render policy links whose pages exist (or that are explicitly configured). {% endcomment %}
+              {% assign _privacy = site.html_pages | where: "url", "/privacy-policy/" | first %}
+              {% unless _privacy %}{% assign _privacy = site.html_pages | where: "url", "/privacy-policy" | first %}{% endunless %}
+              {% if _privacy or site.privacy_policy_url %}
+                <li class="list-inline-item"><a href="{{ site.privacy_policy_url | default: '/privacy-policy' | relative_url }}" class="text-light text-decoration-none">Privacy Policy</a></li>
+              {% endif %}
+              {% assign _terms = site.html_pages | where: "url", "/terms-of-service/" | first %}
+              {% unless _terms %}{% assign _terms = site.html_pages | where: "url", "/terms-of-service" | first %}{% endunless %}
+              {% if _terms or site.terms_of_service_url %}
+                <li class="list-inline-item"><a href="{{ site.terms_of_service_url | default: '/terms-of-service' | relative_url }}" class="text-light text-decoration-none">Terms of Service</a></li>
+              {% endif %}
               <li class="list-inline-item">
                 <a href="#" class="text-light text-decoration-none" data-bs-toggle="modal" data-bs-target="#cookieSettingsModal">
                   Cookie Preferences

data/_includes/navigation/local-graph.html

@@ -0,0 +1,44 @@
+{%- comment -%}
+  ===================================================================
+  LOCAL GRAPH WIDGET — sidebar mini graph
+  ===================================================================
+
+  File: local-graph.html
+  Path: _includes/navigation/local-graph.html
+  Purpose: Renders a small "local graph" of the current page and its
+           immediate wiki-link neighbors in the left sidebar (Obsidian-
+           style local graph view).
+
+  Behavior:
+  - Reads /assets/data/wiki-index.json
+  - Finds the current page by window.location.pathname (with title/basename
+    fallback for permalink quirks)
+  - BFS depth=1 by default (current + direct neighbors, in & out)
+  - Hides itself if the current page is not in the wiki-index, has no
+    neighbors, or the index can't be loaded
+  - Lazily loads cytoscape.js from CDN with SRI + crossorigin
+
+  Opt-out: set `local_graph: false` in page front matter.
+
+  Configurable depth: `local_graph_depth: 2` in page front matter (default 1).
+  ===================================================================
+{%- endcomment -%}
+{%- if page.local_graph != false -%}
+{%- assign lg_depth = page.local_graph_depth | default: 1 -%}
+<div class="obsidian-local-graph-widget mb-3" aria-label="Local graph">
+  <div class="d-flex align-items-center justify-content-between mb-1">
+    <span class="text-uppercase fw-semibold small text-secondary">
+      <i class="bi bi-diagram-3 me-1" aria-hidden="true"></i>Local graph
+    </span>
+    <a href="{{ '/docs/obsidian/graph/' | relative_url }}"
+       class="small text-decoration-none"
+       title="Open the full site graph">full&nbsp;&rsaquo;</a>
+  </div>
+  <div id="obsidian-local-graph"
+       data-depth="{{ lg_depth }}"
+       data-index-url="{{ '/assets/data/wiki-index.json' | relative_url }}"
+       role="img"
+       aria-label="Local graph of pages linked to this page"></div>
+</div>
+<script src="{{ '/assets/js/obsidian-local-graph.js' | relative_url }}" defer></script>
+{%- endif -%}

data/_includes/navigation/sidebar-left.html

@@ -48,6 +48,12 @@
   <!-- Scrollable content area with dynamic navigation options -->
   <div class="offcanvas-body overflow-auto">
 
+    <!-- ========================== -->
+    <!-- LOCAL GRAPH WIDGET        -->
+    <!-- ========================== -->
+    <!-- Mini Obsidian-style local graph of the current page + neighbors -->
+    {% include navigation/local-graph.html %}
+
     <!-- ========================== -->
     <!-- AUTO MODE: Collection Docs -->
     <!-- ========================== -->

data/_layouts/default.html

@@ -86,6 +86,15 @@ layout: root
         <!-- Where the actual page content is rendered -->
         <div class="bd-content ps-lg-2">
             {{ content }}
+
+            {%- comment -%}
+              Optional Obsidian-style backlinks panel. Opt-in for the generic
+              default layout via `backlinks: true` in front matter (the `note`
+              layout enables it by default).
+            {%- endcomment -%}
+            {% if page.backlinks == true %}
+              {% include content/backlinks.html %}
+            {% endif %}
         </div>
     </main>
 </div>

data/_layouts/note.html

@@ -222,7 +222,13 @@ layout: default
       {% include content/giscus.html %}
     </div>
   {% endif %}
-  
+    <!-- ================================ -->
+  <!-- BACKLINKS — "Linked mentions"    -->
+  <!-- ================================ -->
+  <!-- Obsidian-style panel of pages that wiki-link or markdown-link to this note. -->
+  <!-- Disable per-page with `backlinks: false` in front matter. -->
+  {% include content/backlinks.html %}
+
 </article>
 
 <!-- ================================ -->

data/_layouts/welcome.html

@@ -272,7 +272,7 @@ is set in `_config.yml`.
               <code>_about/</code>. Enable them in <code>_config.yml</code>.
             </p>
             <a class="btn btn-sm btn-outline-primary"
-               href="https://github.com/bamr87/zer0-mistakes#content-creation"
+               href="https://github.com/bamr87/zer0-mistakes/blob/main/README.md#-quick-start"
                target="_blank" rel="noopener">
               Content guide <i class="bi bi-box-arrow-up-right"></i>
             </a>
@@ -290,7 +290,7 @@ is set in `_config.yml`.
               your repo to override theme styles without forking.
             </p>
             <a class="btn btn-sm btn-outline-success"
-               href="https://github.com/bamr87/zer0-mistakes#customisation"
+               href="https://github.com/bamr87/zer0-mistakes/blob/main/README.md#-key-features"
                target="_blank" rel="noopener">
               Customisation <i class="bi bi-box-arrow-up-right"></i>
             </a>