Add changelog, update docs for audit fixes, add CI workflow

Docs:
- Add changelog.md page documenting v0.2.0 security hardening and v0.1.0 initial release
- Update reference.md: port validation docs, new troubleshooting entries for port/path errors
- Update internals.md: document config type validation, parser XSS protection, code fence
  tracking, unclosed block handling, data- attribute support, path traversal guards
- Update configuration.md: note on favicon path security and pages type requirement
- Add "Project" nav group with changelog link to docs.yaml

CI:
- Add ci.yml workflow: Python syntax check, pycodestyle lint, multi-version build
  verification (3.9 + 3.12), smoke tests for config validation, path traversal,
  XSS rejection, port validation, and parser edge cases
- Update deploy.yml to use requirements.txt instead of hardcoded pip install

Author: gbasran

.github/workflows/ci.yml

@@ -0,0 +1,122 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Check syntax (py_compile)
+        run: python3 -m py_compile phosphor/cli.py phosphor/build.py phosphor/config.py phosphor/parser.py phosphor/renderer.py phosphor/search.py
+
+      - name: Check formatting (basic style)
+        run: |
+          pip install pycodestyle
+          pycodestyle --max-line-length=160 --ignore=E501,W503 phosphor/
+
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Build phosphor-docs site
+        run: python3 -m phosphor.cli build .
+
+      - name: Verify build output
+        run: |
+          test -d _site
+          test -f _site/index.html
+          test -f _site/changelog.html
+          test -f _site/assets/style.css
+          test -f _site/assets/search.js
+          test -f _site/assets/favicon.svg
+          echo "Build output verified: all expected files present"
+
+      - name: Verify page count
+        run: |
+          count=$(ls _site/*.html | wc -l)
+          echo "Built $count pages"
+          test "$count" -ge 6
+
+  smoke-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Test config validation rejects bad types
+        run: |
+          tmpdir=$(mktemp -d)
+          echo 'pages: "not-a-list"' > "$tmpdir/docs.yaml"
+          mkdir -p "$tmpdir/pages"
+          if python3 -m phosphor.cli build "$tmpdir" 2>&1; then
+            echo "FAIL: should have rejected string pages"
+            exit 1
+          fi
+          echo "PASS: invalid config type rejected"
+
+      - name: Test path traversal blocked
+        run: |
+          python3 -c "
+          from phosphor.build import _is_safe_path
+          import os, tempfile
+          d = tempfile.mkdtemp()
+          assert not _is_safe_path(os.path.join(d, '../../etc/passwd'), d)
+          print('PASS: path traversal blocked')
+          "
+
+      - name: Test XSS URL rejection
+        run: |
+          python3 -c "
+          from phosphor.parser import _escape_url
+          assert _escape_url('javascript:alert(1)') == '#'
+          assert _escape_url('https://example.com') == 'https://example.com'
+          print('PASS: javascript: URIs rejected')
+          "
+
+      - name: Test port validation
+        run: |
+          python3 -c "
+          port = 99999
+          assert not (1 <= port <= 65535), 'Port 99999 should be invalid'
+          port = 8000
+          assert 1 <= port <= 65535, 'Port 8000 should be valid'
+          print('PASS: port validation logic correct')
+          "
+
+      - name: Test parser edge cases
+        run: |
+          python3 -c "
+          from phosphor.parser import parse_markdown
+          # Code fence inside ::: block
+          md = ':::tip Test\n\`\`\`\n::: not a closer\n\`\`\`\n:::'
+          html, _ = parse_markdown(md)
+          assert 'callout' in html, 'Tip block should render'
+          print('PASS: code fence inside ::: block')
+          "

.github/workflows/deploy.yml

@@ -24,7 +24,7 @@ jobs:
         with:
           python-version: "3.12"
 
-      - run: pip install pyyaml
+      - run: pip install -r requirements.txt
 
       - run: python3 -m phosphor.cli build .
 

docs.yaml

@@ -121,10 +121,18 @@ nav:
         page: "internals.md"
         anchor: "extending-phosphor"
 
+  - group: "Project"
+    items:
+      - label: "Changelog"
+        icon: "scroll-text"
+        page: "changelog.md"
+        anchor: "changelog"
+
 pages:
   - index.md
   - getting-started.md
   - writing-content.md
   - configuration.md
   - reference.md
   - internals.md
+  - changelog.md

pages/changelog.md

@@ -0,0 +1,66 @@
+## Changelog
+
+Release history for Phosphor Docs. Each entry documents what changed and why.
+
+## v0.2.0 — Security Hardening & Robustness
+
+Released 2026-02-18.
+
+A comprehensive security and stability audit uncovered 40+ issues across the parser, build system, config loader, CLI, and renderer. All have been fixed in this release.
+
+### Security Fixes
+
+:::warn Critical — update recommended
+These fixes address real security vulnerabilities. If you accept user-contributed content (Markdown files, config values), update immediately.
+:::
+
+- **XSS in URLs**: All links, images, and hero buttons now escape URLs and reject `javascript:` URIs
+- **Path traversal in build**: Custom favicon paths and page file paths are validated to stay within the project directory. Paths containing `../` that escape the project are rejected
+- **SVG injection in favicon**: Theme color values injected into auto-generated favicons are now validated against safe patterns (`#hex` or `rgba()`)
+
+### Parser Fixes
+
+- **Code fences inside `:::` blocks**: A `:::` delimiter inside a code fence (` ``` `) is no longer treated as a component close. You can now safely show `:::` syntax in code examples within callouts, accordions, and other components
+- **Unclosed `:::` blocks**: If a `:::tip` or other component block is never closed, the parser now warns to stderr and renders the content instead of silently consuming the rest of the file
+- **Hyphenated component types**: The depth tracking regex now matches types like `decision-grid` (previously only matched `\w+` which excludes hyphens)
+- **Heading regex performance**: Limited a repeating group in heading extraction to prevent potential catastrophic backtracking on malformed HTML
+- **Table column padding**: Short table rows are now padded with empty cells to match the header column count, preventing misaligned tables
+- **`data-` attribute support**: Component attribute parsing now accepts hyphenated names like `data-x="value"`
+
+### Config & Build Robustness
+
+- **Config type validation**: The config loader now validates that `pages` and `nav` are lists, `site` and `theme` are mappings. Wrong types produce clear error messages instead of downstream crashes
+- **Template existence checks**: Missing `base.html` or `search.js` templates produce a clear error instead of an unhandled exception
+- **Output directory permissions**: Permission denied errors when cleaning `_site/` are caught and reported clearly
+- **Pages directory validation**: The build now checks that `pages/` exists before attempting to read files
+- **Non-string theme values**: Integer or null values in the theme config are silently skipped instead of producing invalid CSS
+
+### CLI Improvements
+
+- **Port validation**: `phosphor serve -p` rejects port numbers outside the valid range (1-65535)
+- **Port-in-use handling**: If the port is already in use, a friendly error message is shown instead of an unhandled exception
+- **Build failure handling**: Build errors during `phosphor serve` and `phosphor build` are caught with a clean error message
+- **Init guard**: `phosphor init` checks that the examples directory exists and handles directory creation failures
+- **SVG MIME type**: The serve command now serves `.svg` files with the correct `image/svg+xml` content type
+
+### Other
+
+- **PyYAML version pin**: Changed from `>=6.0` to `>=6.0,<7.0` to prevent breaking changes from a future major version
+- **install.sh**: Added `$HOME` environment check and chmod error handling
+
+---
+
+## v0.1.0 — Initial Release
+
+Released 2026-02-17.
+
+First public release of Phosphor Docs.
+
+- Extended Markdown parser with 8 component types (callouts, cards, terminal blocks, command blocks, decision grids, accordions, pipelines, hero sections)
+- Dark Terminal Noir theme with full CSS variable theming
+- Client-side fuzzy search with keyboard navigation
+- Auto-themed gradient favicon from accent colors
+- `phosphor build`, `phosphor init`, `phosphor serve` CLI commands
+- Git auto-detection for `phosphor init`
+- GitHub Pages deployment workflow
+- Zero dependencies beyond Python 3 and PyYAML

pages/configuration.md

@@ -133,7 +133,7 @@ pages:
 - Files not listed here are **not built** — this lets you keep drafts in `pages/` without publishing them
 
 :::warn Every page must be listed
-If a Markdown file exists in `pages/` but isn't listed in the `pages` array, it won't be included in the build. This is intentional — it gives you control over what gets published.
+If a Markdown file exists in `pages/` but isn't listed in the `pages` array, it won't be included in the build. This is intentional — it gives you control over what gets published. The `pages` field must be a YAML list — strings or other types produce a clear error message.
 :::
 
 ## Navigation
@@ -463,7 +463,7 @@ site:
   favicon: "my-favicon.svg"
 ```
 
-Place the favicon file in your project directory (next to `docs.yaml`). SVG format is recommended. Custom favicons are copied as-is and not themed.
+Place the favicon file in your project directory (next to `docs.yaml`). SVG format is recommended. Custom favicons are copied as-is and not themed. The path must resolve within your project directory — paths that escape via `../` are rejected for security.
 
 ### Layout Breakpoints
 

pages/internals.md

@@ -24,12 +24,12 @@ Config -> Parse -> Search -> Render -> Output
 Orchestrator. Loads config, iterates over pages, calls parser/renderer/search, copies assets, writes output. The only module that does file I/O for the build.
 ::
 
-::card{icon="settings" color="amber" title="config.py (38 lines)"}
-Loads docs.yaml with PyYAML, merges with DEFAULTS dict. Returns a plain dict. No validation beyond YAML parsing.
+::card{icon="settings" color="amber" title="config.py (~60 lines)"}
+Loads docs.yaml with PyYAML, merges with DEFAULTS dict. Validates types: `pages` and `nav` must be lists, `site` and `theme` must be mappings. Exits with clear error on invalid types.
 ::
 
-::card{icon="code" color="blue" title="parser.py (~550 lines)"}
-The largest module. Two-pass Markdown-to-HTML converter. Pass 1: fenced component blocks. Pass 2: standard Markdown. No external Markdown library.
+::card{icon="code" color="blue" title="parser.py (~650 lines)"}
+The largest module. Two-pass Markdown-to-HTML converter. Pass 1: fenced component blocks (with code fence tracking). Pass 2: standard Markdown. Includes XSS protection for URLs and `javascript:` URI rejection. No external Markdown library.
 ::
 
 ::card{icon="layout-grid" color="purple" title="renderer.py (98 lines)"}
@@ -87,14 +87,18 @@ The h2 heading gets an auto-generated slug ID via `slugify()`. The h3 headings a
 The regex for `:::` block detection:
 
 ```
-^:::(tip|info|warn|cards|decision-grid|command|accordion|pipeline|hero)\s*(\{[^}]*\})?\s*(.*)$
+^:::([a-z][a-z0-9-]*)\s*(\{[^}]*\})?\s*(.*)$
 ```
 
-- Group 1: block type (required)
+- Group 1: block type — supports hyphenated names like `decision-grid` (required)
 - Group 2: attribute string like `{title="..." usage="..."}` (optional)
 - Group 3: inline text after the type (used for callout titles like `:::tip My Title`)
 
-Nesting is tracked with a depth counter. Each `:::\w+` increments depth, each `:::` (bare) decrements. When depth hits 0, the block is closed.
+Nesting is tracked with a depth counter. Each `:::type` increments depth, each `:::` (bare) decrements. When depth hits 0, the block is closed.
+
+**Code fence awareness**: The fenced block scanner tracks code fence state. A `:::` delimiter inside a code fence (`` ``` ``) is ignored — it does not open or close a component block. This prevents content corruption when showing `:::` syntax examples inside code blocks.
+
+**Unclosed blocks**: If a `:::type` block never finds its closing `:::`, the parser emits a warning to stderr and treats the remaining content as the block body rather than silently consuming it.
 
 ### How Code Fences Work
 
@@ -125,21 +129,24 @@ Cards and commands use `::child{attrs}` syntax (double colon, no triple). These
 ::flag\{([^}]*)\}\s*\n(.*?)(?=::flag|\Z)
 ```
 
-Each child's attribute string is parsed by `_parse_attrs()` which extracts `key="value"` pairs.
+Each child's attribute string is parsed by `_parse_attrs()` which extracts `key="value"` pairs. Attribute names support hyphens (e.g., `data-x="value"`) in addition to standard alphanumeric names.
 
 ### Inline Processing
 
 The `_inline(text)` function handles inline Markdown within any line:
 
-1. Images: `![alt](src)` -> `<img>`
-2. Links with classes: `[text](url){.class}` -> `<a class="hero-btn class">`
-3. Regular links: `[text](url)` -> `<a>`
-4. Inline code: `` `code` `` -> `<code>`
+1. **Code spans extracted first** — replaced with placeholders to protect from further processing
+2. Images: `![alt](src)` -> `<img>` (URL escaped, alt text escaped)
+3. Links with classes: `[text](url){.class}` -> `<a class="hero-btn class">`
+4. Regular links: `[text](url)` -> `<a>`
 5. Bold: `**text**` -> `<strong>`
 6. Italic: `*text*` -> `<em>`
+7. **Code spans restored** from placeholders
 
 Order matters — images are processed before links to prevent `![` being matched as a regular link.
 
+**URL security**: All URLs in links, images, and hero buttons are processed through `_escape_url()`, which HTML-escapes special characters (quotes, ampersands) and rejects `javascript:` URIs by replacing them with `#`.
+
 ### HTML Block Pass-Through
 
 After pass 1, the text contains embedded HTML from component parsers. Pass 2 must not wrap these in `<p>` tags. The HTML block detection regex matches lines starting with known block-level HTML tags (both opening and closing):
@@ -173,15 +180,17 @@ The `build(project_dir)` function:
 
 4. **Cleans output**: Deletes `_site/` entirely and recreates it. Every build is a clean build.
 
-5. **Copies assets**: Copies `style.css`, `script.js`, and `favicon.svg` from `theme/` to `_site/assets/`. If a custom favicon is specified in config, it's copied over the default.
+5. **Copies assets**: Copies `style.css`, `script.js`, and `favicon.svg` from `theme/` to `_site/assets/`. If a custom favicon is specified in config, it's copied only if the path resolves within the project directory (path traversal protection). Auto-generated favicons validate that theme colors match safe patterns (`#hex` or `rgba()`) before injecting them into SVG.
 
-6. **Parses pages**: For each `.md` file in the `pages` config array, reads the file from `pages/` directory, calls `parser.parse_markdown()`, and stores the result.
+6. **Validates and parses pages**: Checks that `pages/` directory exists. For each `.md` file in the `pages` config array, verifies the resolved path stays within `pages/` (path traversal protection), then reads the file and calls `parser.parse_markdown()`.
 
 7. **Generates search**: Calls `search.build_search_index()` with all parsed page data. Injects the JSON index into the search.js template and writes it to `_site/assets/search.js`.
 
 8. **Renders pages**: For each parsed page, calls `renderer.render_page()` which substitutes template variables and writes the HTML to `_site/`.
 
-### Config Defaults
+### Config Validation and Defaults
+
+The config loader validates types before merging with defaults. `pages` and `nav` must be lists (or null/absent for defaults). `site` and `theme` must be mappings. Invalid types produce a clear error message and exit.
 
 When `docs.yaml` is missing a field, these defaults apply:
 

pages/reference.md

@@ -25,13 +25,14 @@ Site built to /home/user/my-docs/_site/
 
 The build process:
 
-1. Loads and validates `docs.yaml`
-2. Reads each `.md` file listed in the `pages` array
-3. Parses Markdown into HTML (standard + extended components)
-4. Generates the search index from all headings and content
-5. Renders each page into the base HTML template
-6. Copies theme assets (CSS, JS, favicon) to `_site/assets/`
-7. Writes the final HTML files to `_site/`
+1. Loads and validates `docs.yaml` (checks types: `pages` and `nav` must be lists, `site` and `theme` must be mappings)
+2. Verifies that `pages/` directory exists and that all page paths stay within it (path traversal protection)
+3. Reads each `.md` file listed in the `pages` array
+4. Parses Markdown into HTML (standard + extended components)
+5. Generates the search index from all headings and content
+6. Renders each page into the base HTML template
+7. Copies theme assets (CSS, JS, favicon) to `_site/assets/`
+8. Writes the final HTML files to `_site/`
 
 :::info Clean builds
 Every build deletes and recreates the `_site/` directory from scratch. This ensures no stale files remain from previous builds. The `_site/` directory should be in your `.gitignore`.
@@ -83,11 +84,11 @@ Key behaviors:
 Path to the project directory containing `docs.yaml`. Defaults to the current directory.
 ::
 ::flag{name="--port" short="-p"}
-Port number for the local HTTP server. Defaults to 8000.
+Port number for the local HTTP server (1-65535). Defaults to 8000.
 ::
 :::
 
-Builds the site and starts a local HTTP server for previewing. This is a convenience command that combines `phosphor build` with Python's built-in HTTP server.
+Builds the site and starts a local HTTP server for previewing. This is a convenience command that combines `phosphor build` with Python's built-in HTTP server. Port numbers outside the valid range (1-65535) are rejected with a clear error. If the port is already in use, Phosphor prints a helpful message instead of crashing.
 
 ```terminal
 $ phosphor serve
@@ -202,7 +203,7 @@ The base HTML template at `templates/base.html` defines the page shell:
 | Dependency | Version | Purpose |
 | --- | --- | --- |
 | Python 3 | 3.8+ | Runtime |
-| PyYAML | 6.0+ | `docs.yaml` parsing |
+| PyYAML | 6.0 - 6.x | `docs.yaml` parsing |
 | Lucide Icons | CDN (latest) | Icon library (loaded at runtime from CDN) |
 | Google Fonts | CDN | Chakra Petch, Nunito Sans, JetBrains Mono |
 
@@ -313,6 +314,22 @@ The search index might be empty. Verify:
 If your docs project is on the Windows filesystem (`/mnt/c/...`), file operations are slow due to the WSL2 filesystem bridge. Move your project to the Linux filesystem (`~/my-docs/`) for faster builds.
 :::
 
+:::accordion{title="Error: port must be between 1 and 65535"}
+The port number passed to `phosphor serve -p` is out of range. Use a port between 1 and 65535. Common choices: 3000, 5000, 8000, 8080.
+:::
+
+:::accordion{title="Error: port is already in use"}
+Another process is using that port. Either stop the other process or use a different port: `phosphor serve -p 3001`
+:::
+
+:::accordion{title="Error: page path escapes pages/ directory"}
+A file in the `pages` list references a path outside the `pages/` directory (e.g., `../../../etc/passwd`). Page paths must be simple filenames within the `pages/` directory. Remove any `../` or absolute paths from the `pages` list.
+:::
+
+:::accordion{title="Error: favicon path escapes project directory"}
+The `favicon` value in `docs.yaml` points outside the project directory. The favicon path must be relative and resolve within the project root. Remove any `../` sequences that escape the project.
+:::
+
 :::accordion{title="Lucide icons not rendering"}
 Icons appear as empty squares or text. This means the Lucide CDN script isn't loading. Check:
 1. You have internet connectivity (Lucide loads from `unpkg.com`)