diff --git a/.github/workflows/deploy-gh-pages.yml b/.github/workflows/deploy-gh-pages.yml
index 11bd2a25..63eab857 100644
--- a/.github/workflows/deploy-gh-pages.yml
+++ b/.github/workflows/deploy-gh-pages.yml
@@ -33,7 +33,7 @@ jobs:
       - name: Build with Jekyll
         uses: actions/jekyll-build-pages@v1
         with:
-          source: ./docs
+          source: ./docs/site
           destination: ./_site
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
diff --git a/.gitignore b/.gitignore
index c168850f..249e759f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -403,3 +403,12 @@ claude.md
 **/claude-tasks.md
 **/baseline-benchmarks.md
 /nuget.config
+
+# Jekyll / GitHub Pages local build
+_site/
+.jekyll-cache/
+.jekyll-metadata
+.sass-cache/
+vendor/
+.bundle/
+docs/site/Gemfile.lock
diff --git a/Hyperbee.Json.slnx b/Hyperbee.Json.slnx
index bc5afd2a..0c90a77e 100644
--- a/Hyperbee.Json.slnx
+++ b/Hyperbee.Json.slnx
@@ -5,7 +5,7 @@
     <File Path="LICENSE" />
     <File Path="README.md" />
     <File Path="version.json" />
-    <Project Path="docs/docs.shproj" />
+    <Project Path="docs/site/docs.shproj" />
   </Folder>
   <Folder Name="/Solution Items/.github/">
     <File Path=".github/dependabot.yml" />
diff --git a/docs/site/Gemfile b/docs/site/Gemfile
new file mode 100644
index 00000000..6380d59a
--- /dev/null
+++ b/docs/site/Gemfile
@@ -0,0 +1,13 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "just-the-docs"
+
+group :jekyll_plugins do
+  gem "jekyll-remote-theme"
+  gem "jekyll-include-cache"
+  gem "jekyll-seo-tag"
+  gem "jekyll-relative-links"
+end
+
+gem "webrick", "~> 1.8"
diff --git a/docs/_config.yml b/docs/site/_config.yml
similarity index 100%
rename from docs/_config.yml
rename to docs/site/_config.yml
diff --git a/docs/_includes/nav_footer_custom.html b/docs/site/_includes/nav_footer_custom.html
similarity index 51%
rename from docs/_includes/nav_footer_custom.html
rename to docs/site/_includes/nav_footer_custom.html
index 0fe6da68..3d0cfcf1 100644
--- a/docs/_includes/nav_footer_custom.html
+++ b/docs/site/_includes/nav_footer_custom.html
@@ -1,3 +1,3 @@
-<footer class="site-footer">
+<footer class="site-footer">
     Hyperbee Json Docs
 </footer>#*
\ No newline at end of file
diff --git a/docs/additional-classes.md b/docs/site/additional-classes.md
similarity index 100%
rename from docs/additional-classes.md
rename to docs/site/additional-classes.md
diff --git a/docs/docs.projitems b/docs/site/docs.projitems
similarity index 100%
rename from docs/docs.projitems
rename to docs/site/docs.projitems
diff --git a/docs/docs.shproj b/docs/site/docs.shproj
similarity index 100%
rename from docs/docs.shproj
rename to docs/site/docs.shproj
diff --git a/docs/index.md b/docs/site/index.md
similarity index 100%
rename from docs/index.md
rename to docs/site/index.md
diff --git a/docs/jsonpatch.md b/docs/site/jsonpatch.md
similarity index 100%
rename from docs/jsonpatch.md
rename to docs/site/jsonpatch.md
diff --git a/docs/jsonpath/comparison.md b/docs/site/jsonpath/comparison.md
similarity index 59%
rename from docs/jsonpath/comparison.md
rename to docs/site/jsonpath/comparison.md
index a66d1691..cab3a280 100644
--- a/docs/jsonpath/comparison.md
+++ b/docs/site/jsonpath/comparison.md
@@ -1,4 +1,4 @@
----
+---
 layout: default
 title: Comparison
 parent: JsonPath
@@ -101,36 +101,36 @@ Here is a performance comparison of various queries on the standard book store d
  | Method                   |       Mean |       Error |     StdDev |  Allocated
  | :----------------------- | ---------: | ----------: | ---------: | ---------:
  | `$..* First()`
- | Hyperbee_JsonElement     |   2.874 μs |   1.6256 μs |  0.0891 μs |    3.52 KB
- | Hyperbee_JsonNode        |   3.173 μs |   0.7979 μs |  0.0437 μs |    3.09 KB
- | JsonEverything_JsonNode  |   3.199 μs |   2.4697 μs |  0.1354 μs |    3.53 KB
- | JsonCons_JsonElement     |   5.976 μs |   8.4042 μs |  0.4607 μs |    8.48 KB
- | Newtonsoft_JObject       |   9.219 μs |   2.9245 μs |  0.1603 μs |   14.22 KB
+ | Hyperbee_JsonElement     |   2.874 us |   1.6256 us |  0.0891 us |    3.52 KB
+ | Hyperbee_JsonNode        |   3.173 us |   0.7979 us |  0.0437 us |    3.09 KB
+ | JsonEverything_JsonNode  |   3.199 us |   2.4697 us |  0.1354 us |    3.53 KB
+ | JsonCons_JsonElement     |   5.976 us |   8.4042 us |  0.4607 us |    8.48 KB
+ | Newtonsoft_JObject       |   9.219 us |   2.9245 us |  0.1603 us |   14.22 KB
  |                          |            |             |            |           
  | `$..*`
- | JsonCons_JsonElement     |   5.674 μs |   3.8650 μs |  0.2119 μs |    8.45 KB
- | Hyperbee_JsonElement     |   7.934 μs |   3.5907 μs |  0.1968 μs |    9.13 KB
- | Hyperbee_JsonNode        |  10.457 μs |   7.7120 μs |  0.4227 μs |   10.91 KB
- | Newtonsoft_JObject       |  10.722 μs |   4.1310 μs |  0.2264 μs |   14.86 KB
- | JsonEverything_JsonNode  |  23.096 μs |  10.8629 μs |  0.5954 μs |   36.81 KB
+ | JsonCons_JsonElement     |   5.674 us |   3.8650 us |  0.2119 us |    8.45 KB
+ | Hyperbee_JsonElement     |   7.934 us |   3.5907 us |  0.1968 us |    9.13 KB
+ | Hyperbee_JsonNode        |  10.457 us |   7.7120 us |  0.4227 us |   10.91 KB
+ | Newtonsoft_JObject       |  10.722 us |   4.1310 us |  0.2264 us |   14.86 KB
+ | JsonEverything_JsonNode  |  23.096 us |  10.8629 us |  0.5954 us |   36.81 KB
  |                          |            |             |            |           
  | `$..price`
- | Hyperbee_JsonElement     |   4.428 μs |   4.6731 μs |  0.2561 μs |     4.2 KB
- | JsonCons_JsonElement     |   5.355 μs |   1.1624 μs |  0.0637 μs |    5.65 KB
- | Hyperbee_JsonNode        |   7.931 μs |   0.6970 μs |  0.0382 μs |    7.48 KB
- | Newtonsoft_JObject       |  10.334 μs |   8.2331 μs |  0.4513 μs |    14.4 KB
- | JsonEverything_JsonNode  |  17.000 μs |  14.9812 μs |  0.8212 μs |   27.63 KB
+ | Hyperbee_JsonElement     |   4.428 us |   4.6731 us |  0.2561 us |     4.2 KB
+ | JsonCons_JsonElement     |   5.355 us |   1.1624 us |  0.0637 us |    5.65 KB
+ | Hyperbee_JsonNode        |   7.931 us |   0.6970 us |  0.0382 us |    7.48 KB
+ | Newtonsoft_JObject       |  10.334 us |   8.2331 us |  0.4513 us |    14.4 KB
+ | JsonEverything_JsonNode  |  17.000 us |  14.9812 us |  0.8212 us |   27.63 KB
  |                          |            |             |            |           
  | `$.store.book[?(@.price == 8.99)]`
- | Hyperbee_JsonElement     |   4.153 μs |   3.6089 μs |  0.1978 μs |    5.24 KB
- | JsonCons_JsonElement     |   4.873 μs |   1.0395 μs |  0.0570 μs |    5.05 KB
- | Hyperbee_JsonNode        |   6.980 μs |   5.1007 μs |  0.2796 μs |       8 KB
- | Newtonsoft_JObject       |  10.629 μs |   3.9096 μs |  0.2143 μs |   15.84 KB
- | JsonEverything_JsonNode  |  11.133 μs |   7.2544 μs |  0.3976 μs |   15.85 KB
+ | Hyperbee_JsonElement     |   4.153 us |   3.6089 us |  0.1978 us |    5.24 KB
+ | JsonCons_JsonElement     |   4.873 us |   1.0395 us |  0.0570 us |    5.05 KB
+ | Hyperbee_JsonNode        |   6.980 us |   5.1007 us |  0.2796 us |       8 KB
+ | Newtonsoft_JObject       |  10.629 us |   3.9096 us |  0.2143 us |   15.84 KB
+ | JsonEverything_JsonNode  |  11.133 us |   7.2544 us |  0.3976 us |   15.85 KB
  |                          |            |             |            |           
  | `$.store.book[0]`
- | Hyperbee_JsonElement     |   2.677 μs |   2.2733 μs |  0.1246 μs |    2.27 KB
- | Hyperbee_JsonNode        |   3.126 μs |   3.5345 μs |  0.1937 μs |    2.77 KB
- | JsonCons_JsonElement     |   3.229 μs |   0.0681 μs |  0.0037 μs |    3.21 KB
- | JsonEverything_JsonNode  |   4.612 μs |   2.0037 μs |  0.1098 μs |    5.96 KB
- | Newtonsoft_JObject       |   9.627 μs |   1.1498 μs |  0.0630 μs |   14.56 KB
+ | Hyperbee_JsonElement     |   2.677 us |   2.2733 us |  0.1246 us |    2.27 KB
+ | Hyperbee_JsonNode        |   3.126 us |   3.5345 us |  0.1937 us |    2.77 KB
+ | JsonCons_JsonElement     |   3.229 us |   0.0681 us |  0.0037 us |    3.21 KB
+ | JsonEverything_JsonNode  |   4.612 us |   2.0037 us |  0.1098 us |    5.96 KB
+ | Newtonsoft_JObject       |   9.627 us |   1.1498 us |  0.0630 us |   14.56 KB
diff --git a/docs/jsonpath/functions.md b/docs/site/jsonpath/functions.md
similarity index 99%
rename from docs/jsonpath/functions.md
rename to docs/site/jsonpath/functions.md
index 7c460d1a..8b4c36c6 100644
--- a/docs/jsonpath/functions.md
+++ b/docs/site/jsonpath/functions.md
@@ -1,4 +1,4 @@
----
+---
 layout: default
 title: Functions
 parent: JsonPath
diff --git a/docs/jsonpath/jsonpath.md b/docs/site/jsonpath/jsonpath.md
similarity index 99%
rename from docs/jsonpath/jsonpath.md
rename to docs/site/jsonpath/jsonpath.md
index 4bb161d4..a439a83e 100644
--- a/docs/jsonpath/jsonpath.md
+++ b/docs/site/jsonpath/jsonpath.md
@@ -1,4 +1,4 @@
----
+---
 layout: default
 title: JsonPath
 has_children: true
diff --git a/docs/jsonpath/overview.md b/docs/site/jsonpath/overview.md
similarity index 99%
rename from docs/jsonpath/overview.md
rename to docs/site/jsonpath/overview.md
index 2f0016ec..e4391f7f 100644
--- a/docs/jsonpath/overview.md
+++ b/docs/site/jsonpath/overview.md
@@ -1,4 +1,4 @@
----
+---
 layout: default
 title: Overview
 parent: JsonPath
diff --git a/docs/jsonpath/syntax.md b/docs/site/jsonpath/syntax.md
similarity index 100%
rename from docs/jsonpath/syntax.md
rename to docs/site/jsonpath/syntax.md
diff --git a/docs/jsonpointer.md b/docs/site/jsonpointer.md
similarity index 100%
rename from docs/jsonpointer.md
rename to docs/site/jsonpointer.md
diff --git a/docs/site/local-jekyll.md b/docs/site/local-jekyll.md
new file mode 100644
index 00000000..ade9f4b4
--- /dev/null
+++ b/docs/site/local-jekyll.md
@@ -0,0 +1,427 @@
+# Running Jekyll Docs Locally (Docker)
+
+Reusable recipe for previewing `just-the-docs` / GitHub Pages sites locally
+using a throwaway `ruby:3.3` container. Works for any repo -- BlazorX, Hyperbee,
+anything else that follows the same docs convention.
+
+No Ruby install required. Docker Desktop is the only dependency.
+
+---
+
+## First-time setup (teammate onboarding)
+
+Skip this section if you already have Docker and a bash shell working.
+
+### 1. Install Docker Desktop
+
+**Windows / macOS**: download from https://www.docker.com/products/docker-desktop/
+and run the installer. Defaults are fine. On Windows it prompts to enable
+WSL 2 -- accept.
+
+**Linux**: install Docker Engine per your distro's instructions. You do
+not need Docker Desktop specifically; any `docker` CLI that can pull
+public images works.
+
+**Licensing note**: Docker Desktop is free for personal use, education,
+non-commercial open-source work, and companies with fewer than 250
+employees AND less than $10M in annual revenue. Larger companies need
+paid subscriptions. Check the current terms before using it in
+a commercial setting.
+
+### 2. Start Docker and verify
+
+Launch Docker Desktop (Windows/macOS) and wait for the whale icon in
+the system tray to settle. Then in a terminal:
+
+```bash
+docker --version
+docker run --rm hello-world
+```
+
+The first command prints the Docker version. The second pulls and runs
+a tiny test image -- if it prints "Hello from Docker!", you're set.
+
+### 3. Pick a shell
+
+The `docker run` command below works from any shell, but the
+`MSYS_NO_PATHCONV=1` prefix is a Git Bash specific workaround for a
+path-translation bug on Windows. Your options:
+
+- **Git Bash** (Windows) -- use the commands as written. Get it bundled
+  with Git for Windows at https://git-scm.com/
+- **WSL 2** (Windows) -- drop the `MSYS_NO_PATHCONV=1` prefix; WSL
+  doesn't need it. Paths also change from `C:/...` to `/mnt/c/...`.
+- **PowerShell** (Windows) -- drop the prefix; use backticks instead
+  of backslashes for line continuation.
+- **macOS / Linux terminal** -- drop the prefix; paths are already
+  POSIX.
+
+### 4. Pre-pull the image (optional but recommended)
+
+The first `docker run` in the Quick-start section pulls `ruby:3.3`
+(~900 MB). You can do this explicitly up front so the first actual
+use starts fast:
+
+```bash
+docker pull ruby:3.3
+```
+
+After this, every container we spin up reuses the cached image.
+
+---
+
+## Prerequisites (for a running environment)
+
+1. **Docker running** -- verified via `docker --version` and `docker info`.
+2. A project with a `docs/` folder (or `docs/site/`, or wherever you keep
+   Jekyll sources) containing:
+   - `_config.yml`
+   - `Gemfile`
+   - Your markdown content.
+3. Git Bash, WSL, or another bash-capable shell (the `MSYS_NO_PATHCONV`
+   trick below is specifically for Git Bash on Windows).
+
+---
+
+## Quick-start command
+
+From the project root, pick a port and run:
+
+```bash
+MSYS_NO_PATHCONV=1 docker run --rm --name my-jekyll \
+  -v "C:/path/to/project/docs/site:/srv/jekyll" \
+  -w /srv/jekyll -p 4000:4000 \
+  ruby:3.3 \
+  sh -c "bundle install --quiet && bundle exec jekyll serve --host 0.0.0.0 --force_polling"
+```
+
+Then open `http://localhost:4000/<baseurl>/` in your browser, where
+`<baseurl>` is whatever `baseurl` is set to in `_config.yml`
+(for example, `/blazorx/`).
+
+**What each flag does**:
+- `MSYS_NO_PATHCONV=1` -- stops Git Bash from rewriting the Windows path
+  into a POSIX-looking path that Docker then fails to mount.
+- `--rm` -- container is deleted when it stops. No cleanup needed.
+- `--name my-jekyll` -- optional, lets you `docker stop my-jekyll` later.
+- `-v <host-path>:/srv/jekyll` -- bind-mounts your docs folder into the
+  container's working directory.
+- `-w /srv/jekyll` -- makes that the starting directory.
+- `-p 4000:4000` -- publishes port 4000 on your host. Change the left side
+  if 4000 is taken.
+- `ruby:3.3` -- the Debian/glibc Ruby 3.3 image. Avoids the Alpine/musl
+  sass-embedded broken-pipe bug.
+- `sh -c "bundle install --quiet && bundle exec jekyll serve ..."` --
+  installs gems, then runs Jekyll in watch mode.
+- `--host 0.0.0.0` -- needed so the host machine can reach the server
+  through the port mapping.
+- `--force_polling` -- needed on Windows bind mounts for file-change
+  detection to work reliably.
+
+First run downloads `ruby:3.3` (~900 MB). Subsequent runs start in seconds
+because the image is cached locally.
+
+---
+
+## What each repo needs
+
+### `docs/<path>/_config.yml`
+
+Minimum viable starting point:
+
+```yaml
+title: My Project
+description: One-line project description
+remote_theme: pmarsceill/just-the-docs
+baseurl: "/myproject/"
+url: "https://example.github.io"
+
+aux_links:
+  "GitHub Repository":
+    - "//github.com/my-org/my-project"
+
+search_enabled: true
+color_scheme: dark
+
+markdown: kramdown
+highlighter: rouge
+permalink: pretty
+
+plugins:
+  - jekyll-remote-theme
+  - jekyll-include-cache
+  - jekyll-seo-tag
+  - jekyll-relative-links
+
+relative_links:
+  enabled: true
+  collections: true
+
+# Optional: Mermaid diagram support (just-the-docs >= 0.5)
+mermaid:
+  version: "10.9.0"
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: "default"
+  # Disable Liquid rendering inside content pages so code fences
+  # containing {{ or }} don't trip the template engine. Adjust the
+  # paths to match your directory layout.
+  - scope:
+      path: "getting-started"
+    values:
+      render_with_liquid: false
+  - scope:
+      path: "guides"
+    values:
+      render_with_liquid: false
+  - scope:
+      path: "reference"
+    values:
+      render_with_liquid: false
+  - scope:
+      path: "index.md"
+    values:
+      render_with_liquid: false
+```
+
+### `docs/<path>/Gemfile`
+
+```ruby
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "just-the-docs"
+
+group :jekyll_plugins do
+  gem "jekyll-remote-theme"
+  gem "jekyll-include-cache"
+  gem "jekyll-seo-tag"
+  gem "jekyll-relative-links"
+end
+
+gem "webrick", "~> 1.8"
+```
+
+### `.gitignore` entries
+
+Add to the repo's root `.gitignore`:
+
+```
+# Jekyll / GitHub Pages local build
+_site/
+.jekyll-cache/
+.jekyll-metadata
+.sass-cache/
+vendor/
+.bundle/
+docs/site/Gemfile.lock
+```
+
+Adjust `docs/site/Gemfile.lock` to match your docs path.
+
+### GitHub Pages workflow (optional, for publishing)
+
+`.github/workflows/deploy-gh-pages.yml`:
+
+```yaml
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./docs/site
+          destination: ./_site
+      - uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+Set `source:` to wherever your docs live (for example `./docs` or `./docs/site`).
+
+---
+
+## Running multiple projects in parallel
+
+Each project gets its own container name and its own host port. The
+`ruby:3.3` image is shared across all of them.
+
+```bash
+# BlazorX on port 4000
+MSYS_NO_PATHCONV=1 docker run --rm --name bzx-jekyll \
+  -v "C:/Development/playground/BlazorX/docs/site:/srv/jekyll" \
+  -w /srv/jekyll -p 4000:4000 ruby:3.3 \
+  sh -c "bundle install --quiet && bundle exec jekyll serve --host 0.0.0.0 --force_polling"
+
+# Hyperbee.Json on port 4001
+MSYS_NO_PATHCONV=1 docker run --rm --name hbjson-jekyll \
+  -v "C:/Development/hyperbee.json/docs:/srv/jekyll" \
+  -w /srv/jekyll -p 4001:4000 ruby:3.3 \
+  sh -c "bundle install --quiet && bundle exec jekyll serve --host 0.0.0.0 --force_polling"
+```
+
+Browse them at `http://localhost:4000/<baseurl>/` and
+`http://localhost:4001/<baseurl>/` simultaneously.
+
+---
+
+## Reusable helper script
+
+Drop this at a well-known location (for example `C:/Development/tools/jekyll-serve.sh`):
+
+```bash
+#!/usr/bin/env bash
+# Start a Jekyll dev container for any project.
+# Usage: jekyll-serve.sh [docs-dir] [host-port]
+set -eu
+
+DOCS_DIR="${1:-$(pwd)/docs/site}"
+PORT="${2:-4000}"
+
+# Absolute path for Docker bind mount
+DOCS_ABS="$(cd "$DOCS_DIR" && pwd)"
+
+# Pick a reasonable container name from the parent folder
+NAME="jekyll-$(basename "$(dirname "$DOCS_ABS")")-$PORT"
+
+echo "Serving $DOCS_ABS on http://localhost:$PORT/"
+echo "Container: $NAME"
+echo "Stop with: docker stop $NAME"
+
+MSYS_NO_PATHCONV=1 docker run --rm --name "$NAME" \
+  -v "${DOCS_ABS}:/srv/jekyll" \
+  -w /srv/jekyll -p "${PORT}:4000" \
+  ruby:3.3 \
+  sh -c "bundle install --quiet && bundle exec jekyll serve --host 0.0.0.0 --force_polling"
+```
+
+Then from any repo:
+
+```bash
+# Uses ./docs/site, port 4000
+~/dev/tools/jekyll-serve.sh
+
+# Custom path
+~/dev/tools/jekyll-serve.sh ./docs
+
+# Custom path and port
+~/dev/tools/jekyll-serve.sh ./docs 4001
+```
+
+---
+
+## Speeding up repeat starts (optional)
+
+On each cold start the container runs `bundle install` and fetches about
+40 gems. That's ~20 seconds. Cache the bundle directory to reuse across
+runs by adding a volume for `/usr/local/bundle`:
+
+```bash
+MSYS_NO_PATHCONV=1 docker run --rm --name my-jekyll \
+  -v "C:/path/to/docs:/srv/jekyll" \
+  -v "jekyll-bundle-cache:/usr/local/bundle" \
+  -w /srv/jekyll -p 4000:4000 ruby:3.3 \
+  sh -c "bundle install --quiet && bundle exec jekyll serve --host 0.0.0.0 --force_polling"
+```
+
+`jekyll-bundle-cache` is a named Docker volume. It persists across
+containers and projects. Remove with `docker volume rm jekyll-bundle-cache`.
+
+---
+
+## Troubleshooting
+
+### `docker: command not found`
+
+Docker is not installed or not on `PATH`. See the First-time setup
+section above. On Windows, restart your terminal after installing
+Docker Desktop so `PATH` picks up the new entries.
+
+### `Cannot connect to the Docker daemon`
+
+Docker is installed but not running. On Windows/macOS, launch
+Docker Desktop and wait for the whale icon to stop animating. On
+Linux, `sudo systemctl start docker` (or `service docker start`).
+
+### "Could not locate Gemfile"
+
+The bind mount did not land where the container expected. On Git Bash you
+need both the `MSYS_NO_PATHCONV=1` prefix and a Windows-style absolute
+path like `C:/path/...` (forward slashes).
+
+### Port already in use
+
+Another process or container has the host port. Check with
+`docker ps --filter "publish=4000"` or just pick a different port on the
+left side of `-p host:container`.
+
+### Mermaid diagrams don't render
+
+Your `_config.yml` needs a `mermaid:` block with a `version:` key, and
+your markdown must use ``` ```mermaid ``` fenced blocks. The theme
+JavaScript replaces the code block with rendered SVG on page load --
+nothing needs to run server-side.
+
+### SCSS errors ("expected }")
+
+You probably set `render_with_liquid: false` too broadly. Scope it to
+content directories only (see the `defaults` block in `_config.yml`
+above). The theme's SCSS files genuinely need Liquid for
+`{% include %}` directives.
+
+### Links ending in `.md` return 404
+
+Install `jekyll-relative-links` (see `Gemfile` and `_config.yml`
+templates above). Without it, Jekyll does not rewrite `[text](foo.md)`
+links to the final rendered URL.
+
+### File changes not picked up
+
+Windows bind mounts need `--force_polling` on the `jekyll serve` command.
+Without it, Jekyll uses inotify/fsevent which do not fire across the
+Docker VM boundary.
+
+### `_config.yml` edits seem to be ignored
+
+Jekyll does not auto-reload `_config.yml` even with `--force_polling`.
+Stop and restart the container to pick up changes.
+
+---
+
+## Stopping the container
+
+```bash
+docker stop my-jekyll
+```
+
+`--rm` in the run command means the container is removed automatically
+on stop. No manual cleanup.