feat(v0.5): highlight.js + public demo + screenshots + raw-HTML-escape fix (#73)

* feat(v0.5): highlight.js + public demo deployment + README screenshots

Swap server-side Pygments/codehilite for client-side highlight.js v11.9.0
loaded from a pinned jsdelivr CDN. Both GitHub light and GitHub dark themes
ship with every page; the theme toggle now flips the `disabled` flag on the
`<link>` tags so code blocks stay in sync with the page theme. Fenced code
now emits plain `<pre><code class="language-xxx">` via the fenced_code
extension. Removed the optional Pygments dep from pyproject.toml,
setup.sh/.bat, CI workflows, and the bug-report template.

Build a public demo site from eight dummy sessions across three fictional
projects (demo-blog-engine Rust SSG, demo-ml-pipeline DistilBERT fine-tune,
demo-todo-api FastAPI CRUD) under examples/demo-sessions/. The Pages
workflow now copies these into raw/sessions/ at CI time and deploys via
actions/deploy-pages. No personal data.

Embed six headless-Chrome screenshots in the README (home, sessions,
session detail, changelog, projects, code-heavy session) so the landing
page shows the real product immediately.

15 new tests in tests/test_highlightjs.py lock the swap in place:
language classes, CDN URL shape, both page_head variants, foot script init,
absence of pygments symbols, and an end-to-end build_site smoke test.

178 tests passing (was 163).

* fix(v0.5): escape raw HTML tags in session prose (#74)

A session transcript that mentioned `<textarea>` in prose was leaking
an unclosed element into the DOM, swallowing every following tag —
including the `<script>` that boots highlight.js. The v0.5 swap from
server-side Pygments to client-side hljs (#73) made this pre-existing
bug catastrophic: once the script was stuck inside a broken textarea,
no code block on the page ever got highlighted.

Add `_EscapeRawHtmlPreprocessor` between `fenced_code` (priority 25)
and `html_block` (priority 20) in the markdown pipeline. It escapes
`<tagname>` / `</tagname>` patterns outside inline backtick spans.
Fenced code (already extracted into placeholders), inline code (via
the preprocessor's own backtick-skipping), HTML comments, bare `<`
in math, blockquotes, tables, and link syntax are all untouched.

9 new regression tests in tests/test_highlightjs.py lock it down.
187 passing (was 178). Verified on a real 169-code-block session
page: 0/172 → 172/172 highlighted after the fix, and the dark-theme
stylesheet swap still works.

Author: Pratiyush

.github/ISSUE_TEMPLATE/bug_report.md

@@ -29,7 +29,7 @@ cd llm-wiki
 - Python version: <!-- `python3 --version` -->
 - llmwiki version: <!-- `python3 -m llmwiki --version` -->
 - Claude Code version (if relevant): <!-- `claude --version` -->
-- `pygments` installed? <!-- yes / no -->
+- Browser (for rendering issues): <!-- highlight.js loads from a CDN; version matters if blocked -->
 
 ## Logs
 

.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Install required deps
         run: |
           python -m pip install --upgrade pip
-          python -m pip install markdown pygments
+          python -m pip install markdown
           python -m pip install ruff pytest
 
       - name: Ruff lint
@@ -75,7 +75,7 @@ jobs:
           python-version: "3.12"
 
       - name: Install deps
-        run: python -m pip install markdown pygments
+        run: python -m pip install markdown
 
       - name: Build against fixtures (when present)
         run: |

.github/workflows/pages.yml

@@ -1,10 +1,12 @@
 name: Deploy demo site to GitHub Pages
 
-# Phase 6.5 Self-Demo — build from synthetic fixtures on tag push and publish
-# to https://pratiyush.github.io/llm-wiki/.
+# Builds a public demo from dummy example sessions (no personal data) and
+# publishes it to GitHub Pages. Triggered on tag pushes, pushes to main, and
+# manual runs. Highlight.js loads client-side from CDN so no extra deps.
 
 on:
   push:
+    branches: ["master", "main"]
     tags: ["v*"]
   workflow_dispatch:
 
@@ -29,20 +31,34 @@ jobs:
           python-version: "3.12"
 
       - name: Install deps
-        run: python -m pip install markdown pygments
+        run: python -m pip install markdown
 
-      - name: Scaffold + seed fixtures
+      - name: Scaffold wiki layout
+        run: python -m llmwiki init
+
+      - name: Seed demo sessions (no real user data)
         run: |
-          python -m llmwiki init
-          # Copy synthetic fixtures (when present) into raw/sessions/
-          if [ -d tests/fixtures/demo ]; then
-            mkdir -p raw/sessions
+          set -e
+          mkdir -p raw/sessions
+          # Primary: richer multi-project demo under examples/demo-sessions/.
+          if [ -d examples/demo-sessions ] && [ "$(ls -A examples/demo-sessions 2>/dev/null)" ]; then
+            cp -r examples/demo-sessions/* raw/sessions/
+            echo "Seeded raw/sessions/ from examples/demo-sessions/"
+          fi
+          # Fallback: older synthetic fixtures (kept for test parity).
+          if [ -d tests/fixtures/demo ] && [ "$(ls -A tests/fixtures/demo 2>/dev/null)" ]; then
             cp -r tests/fixtures/demo/* raw/sessions/
+            echo "Seeded raw/sessions/ from tests/fixtures/demo/"
           fi
+          echo "--- raw/sessions contents ---"
+          find raw/sessions -maxdepth 2 -type f | sort
 
       - name: Build static site
         run: python -m llmwiki build --out ./site
 
+      - name: Ensure .nojekyll for Pages
+        run: touch ./site/.nojekyll
+
       - name: Setup Pages
         uses: actions/configure-pages@v5
 

CHANGELOG.md

@@ -12,9 +12,17 @@ Versions below 1.0 are pre-production — API and file formats may change.
 
 - **Session metrics frontmatter** (#63) — converter now emits five new keys per session as JSON inline: `tool_counts`, `token_totals` (input / cache_creation / cache_read / output), `turn_count`, `hour_buckets` (UTC-normalised ISO-hour → activity count), and `duration_seconds`. Foundation for the v0.8 visualization stack (#64 heatmap / #65 tool chart / #66 token card). Stdlib-only; byte-identical on re-run. 24 new tests.
 - **Changelog page** (#72) — `CHANGELOG.md` now renders as a first-class page at `site/changelog.html` with a nav-bar link, narrow reading column, keep-a-changelog typography, and the same theme/print styles as the rest of the wiki.
+- **highlight.js syntax highlighting** (#73) — replaced server-side Pygments/codehilite with client-side [highlight.js](https://highlightjs.org/) v11.9.0 loaded from a pinned jsdelivr CDN. Both GitHub light (`github.min.css`) and GitHub dark (`github-dark.min.css`) themes are preloaded; the runtime swaps the `disabled` flag on `<link>` tags when the theme toggles so code blocks stay in sync with the rest of the page. Code fences now emit plain `<pre><code class="language-xxx">` via the `fenced_code` extension. Lighter build (no optional Python dep), consistent look across every page, auto-detection for untagged blocks. 15 new tests.
+- **Public demo deployment** (#73) — `.github/workflows/pages.yml` now builds a demo site from the eight dummy sessions under [`examples/demo-sessions/`](examples/demo-sessions) on every push to `master` and deploys it to GitHub Pages. No personal data. Three fictional projects (`demo-blog-engine` Rust SSG, `demo-ml-pipeline` DistilBERT fine-tune, `demo-todo-api` FastAPI CRUD) with realistic code fences so visitors can see highlight.js and the full session UX immediately.
+- **README screenshots** (#73) — added six embedded screenshots under [`docs/images/`](docs/images) (home, sessions index, session detail, changelog, projects index, code-heavy session) captured from the demo site with headless Chrome at 2x device pixel ratio.
+
+### Changed
+
+- **No optional highlight dependency** (#73) — `pip install -e '.[highlight]'` is now a no-op alias kept only for backwards-compatibility with v0.4 install docs. `setup.sh`, `setup.bat`, `pyproject.toml`, and CI workflows no longer install Pygments.
 
 ### Fixed
 
+- **Raw HTML in session prose leaking into the DOM** (#74) — a session transcript that mentioned `<textarea>` (or any tag-shaped substring) in prose used to pass through the markdown library unescaped, leaving an unclosed element that swallowed every following tag — including the `<script>` that boots highlight.js. The v0.5 swap from server-side Pygments to client-side hljs (#73) made this pre-existing bug catastrophic: once the script was inside a stuck textarea, no code block on the page ever got highlighted. Fixed by a new `_EscapeRawHtmlPreprocessor` that runs in the Python `markdown` pipeline after `fenced_code` (priority 25) and before `html_block` (priority 20), escaping `<tagname>` / `</tagname>` patterns outside inline backtick spans. Inline/fenced code, HTML comments (`<!-- llmwiki:metadata -->`), bare `<` in math, blockquotes, tables, headings, and link syntax are all untouched. 9 new regression tests lock it down. Verified on a real 169-code-block session page: 0/172 → 172/172 highlighted after the fix.
 - **Code-fence truncation eating pages** (#72) — `truncate_chars` / `truncate_lines` used to cut content mid-code-block, leaving the opening ` ``` ` without a closing fence. The markdown parser then swallowed everything that followed as one giant block (user-visible example: the "Full Directory Tree" section on subagent pages). Fixed by counting unbalanced fences in the kept portion and injecting a closing fence before the truncation marker. 5 new tests; 30 previously-mangled session files regenerated.
 - **Sync crash on corrupt JSONL bytes** (#72) — a single stray non-UTF-8 byte in a session transcript used to abort the entire `llmwiki sync` run with `UnicodeDecodeError`. `parse_jsonl` now opens with `errors="replace"` and silently drops non-dict records (rare stray scalars from partial writes that previously crashed `filter_records` with `AttributeError`).
 

README.md

@@ -21,14 +21,35 @@ Every Claude Code, Codex CLI, and Cursor session writes a full transcript to dis
 ./build.sh && ./serve.sh           # build + serve at http://127.0.0.1:8765
 ```
 
+> **Live demo:** https://pratiyush.github.io/llm-wiki/ — built from the dummy sessions in [`examples/demo-sessions/`](examples/demo-sessions) by [`.github/workflows/pages.yml`](.github/workflows/pages.yml). No personal data.
+
+## Screenshots
+
+All screenshots below are from the **public demo site** which is built on every `master` push from the dummy example sessions. Your own wiki will look identical — just with your real work.
+
+### Home — projects overview with activity heatmap
+![llmwiki home page — LLM Wiki header, activity heatmap, and a grid of three demo projects (demo-blog-engine, demo-ml-pipeline, demo-todo-api)](docs/images/home.png)
+
+### All sessions — filterable table across every project
+![llmwiki sessions index — activity timeline above a table of eight demo sessions with project, model, date, message count, and tool-call columns](docs/images/sessions.png)
+
+### Session detail — full conversation + tool calls
+![llmwiki session detail — Rust blog engine scaffolding session showing summary, breadcrumbs, a TOML Cargo.toml block and a Rust main.rs block, both highlighted by highlight.js](docs/images/session-rust.png)
+
+### Changelog — renders `CHANGELOG.md` as a first-class page
+![llmwiki changelog page — keep-a-changelog format with colored headings for Added / Fixed / Changed and auto-linked PR references](docs/images/changelog.png)
+
+### Projects index — freshness badges + per-project stats
+![llmwiki projects index — three demo project cards with green/yellow/red freshness badges showing how recently each project was touched](docs/images/projects.png)
+
 ## What you get
 
 ### Human-readable
 - **All your sessions**, converted from `.jsonl` to clean, redacted markdown
 - **A Karpathy-style wiki** — `sources/`, `entities/`, `concepts/`, `syntheses/`, `comparisons/`, `questions/` linked with `[[wikilinks]]`
 - **A beautiful static site** you can browse locally or deploy to GitHub Pages
   - Global search (Cmd+K command palette with fuzzy match over pre-built index)
-  - Pygments syntax highlighting
+  - [highlight.js](https://highlightjs.org/) client-side syntax highlighting (light + dark themes)
   - Dark mode (system-aware + manual toggle with `data-theme`)
   - Keyboard shortcuts: `/` search · `g h/p/s` nav · `j/k` rows · `?` help
   - Collapsible tool-result sections (auto-expand > 500 chars)
@@ -68,7 +89,7 @@ Every page also includes an `<!-- llmwiki:metadata -->` HTML comment that AI age
 - **SessionStart hook** — auto-syncs new sessions in the background on every Claude Code launch
 - **File watcher** — `llmwiki watch` polls agent stores with debounce and runs sync on change
 - **MCP server** — 7 production tools (`wiki_query`, `wiki_search`, `wiki_list_sources`, `wiki_read_page`, `wiki_lint`, `wiki_sync`, `wiki_export`) queryable from any MCP client (Claude Desktop, Cline, Cursor, ChatGPT desktop)
-- **No servers, no database, no npm** — Python stdlib + `markdown` (Pygments optional)
+- **No servers, no database, no npm** — Python stdlib + `markdown`. Syntax highlighting loads from a highlight.js CDN at view time.
 
 ## How it works
 
@@ -137,13 +158,14 @@ setup.bat
 ### With pip (v0.3+)
 
 ```bash
-pip install -e .                # basic
-pip install -e '.[highlight]'   # + Pygments syntax highlighting
+pip install -e .                # basic — everything you need
 pip install -e '.[pdf]'         # + PDF ingestion
 pip install -e '.[dev]'         # + pytest + ruff
 pip install -e '.[all]'         # all of the above
 ```
 
+Syntax highlighting is now powered by [highlight.js](https://highlightjs.org/), loaded from a CDN at view time — no optional deps required.
+
 ### What setup does
 
 1. Creates `raw/`, `wiki/`, `site/` data directories