Update documentation for Vite-based template system

- Update CLAUDE.md with comprehensive Vite workflow instructions
  - Replace Tailwind CSS section with Template Development section
  - Document template structure (templates_src/ → microdocs/templates/)
  - Add npm commands: dev, build, preview
  - Update release process to include template build step
  - Update architecture section with new template system details
- Update README.md with simplified template usage section
  - Reference TEMPLATES.md for full development guide
  - Show examples of using built-in and custom templates
- Add TEMPLATES.md to GitHub Pages deployment workflow
- Add comment to runtests.sh about Playwright

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: 2 people

CLAUDE.md

@@ -44,14 +44,35 @@ ruff check --fix .
 ruff format .
 ```
 
-### Styling (Tailwind CSS)
+### Template Development
 
-**IMPORTANT**: Never edit `microdocs/templates/default.css` directly - it is auto-generated!
+Templates are built using Vite, which compiles HTML, CSS (Tailwind), and JavaScript into single-file outputs.
 
-To modify styles:
-1. Edit `microdocs/templates/default.tailwind.css` (source file)
-2. Run Tailwind CLI to compile: `npx @tailwindcss/cli@latest -i microdocs/templates/default.tailwind.css -o microdocs/templates/default.css --minify`
-3. The compiled/minified CSS will be written to `default.css`
+**Template Structure:**
+- Source: `templates_src/{template_name}/` (root level, not in microdocs/)
+  - `{template_name}.html` - HTML template with Jinja2 markup
+  - `{template_name}.css` - Tailwind CSS source
+  - `{template_name}.js` - JavaScript source
+- Output: `microdocs/templates/{template_name}/{template_name}.html` (single file with inlined CSS/JS)
+
+**Development workflow:**
+```bash
+# Start dev server with hot-reloading
+npm run dev
+
+# Build all templates for production
+npm run build
+
+# Preview built templates
+npm run preview
+```
+
+**IMPORTANT**:
+- Never edit files in `microdocs/templates/` directly - they are auto-generated by Vite!
+- Always edit source files in `templates_src/` (at project root)
+- Run `npm run build` to compile templates after making changes
+- The build process automatically discovers all template directories and builds them
+- `templates_src/` is excluded from PyPI package builds (only compiled templates are distributed)
 
 ### Testing
 
@@ -90,48 +111,53 @@ pytest --cov=microdocs
 
 When creating a new release, follow these steps **in order**:
 
-1. **Run full test suite** - Verify everything passes before releasing
+1. **Build templates** - Ensure templates are up to date
+   ```bash
+   npm run build
+   ```
+
+2. **Run full test suite** - Verify everything passes before releasing
    ```bash
    pytest && ruff check . && ruff format --check .
    ```
 
-2. **Update version** in `pyproject.toml`
+3. **Update version** in `pyproject.toml`
    - Bump version number
    - Update development status classifier if needed (Alpha → Beta → Production/Stable)
 
-3. **Update CHANGELOG.md**
+4. **Update CHANGELOG.md**
    - Move "Unreleased" section to new version heading with date
    - Add summary of changes (Added, Changed, Fixed, etc.)
    - Include deployment instructions with new version number
 
-4. **Commit changes**
+5. **Commit changes**
    ```bash
    git add pyproject.toml CHANGELOG.md
    git commit -m "Release version X.Y.Z"
    ```
 
-5. **Create git tag**
+6. **Create git tag**
    ```bash
    git tag -a vX.Y.Z -m "Release vX.Y.Z: brief description"
    ```
 
-6. **Build the package**
+7. **Build the package**
    ```bash
    uv build
    ```
 
-7. **Publish to PyPI**
+8. **Publish to PyPI**
    ```bash
    uv publish
    ```
 
-8. **Push changes and tags**
+9. **Push changes and tags**
    ```bash
    git push
    git push --tags
    ```
 
-9. **Update floating major version tag** (for GitHub Action compatibility)
+10. **Update floating major version tag** (for GitHub Action compatibility)
    ```bash
    # For v1.x.x releases, update the v1 tag
    git tag -f v1 vX.Y.Z
@@ -178,30 +204,34 @@ When creating a new release, follow these steps **in order**:
      - Returns flat list with level/id/name for each heading
    - `convert_plain_text_to_html(text_content)`: Converts plain text to HTML with line breaks
 
-3. **Template System** (templates/default.html)
-   - Jinja2-based template rendering
-   - Single-page HTML template with Tailwind CSS and Alpine.js
-   - Uses CDN for:
-     - Tailwind CSS (includes forms, typography, aspect-ratio, line-clamp, container-queries plugins)
-     - Alpine.js 3.x for reactive UI
-   - Two-column layout:
-     - Main content area (left, flex-1)
-     - TOC sidebar (right, fixed 16rem width, sticky)
-   - Page-based navigation: sections act like pages, only one visible at a time
-   - Alpine.js state: `activeSection` tracks which section is displayed
-   - First section shown by default
-   - Smooth transitions between sections
-   - Dynamic navigation with active state highlighting
-   - Table of Contents (TOC):
-     - Shows all headings (H1-H6) for current section
-     - Automatically indented based on heading level (0.75rem per level)
-     - Sticky positioning (follows scroll)
-     - Each section has its own TOC
-   - Template variables:
-     - `{{ title }}` - Extracted from first H1 heading in first markdown file or provided via CLI
-     - `{{ sections }}` - List of sections with `id`, `name`, `html`, and `toc` attributes
-     - `{{ inlined_css }}` - CSS content from companion `.css` file
+3. **Template System**
+   - **Build Process**: Templates are built using Vite (see Template Development section)
+   - **Source Location**: `microdocs/templates_src/{template_name}/`
+     - `{template_name}.html` - Jinja2 template with embedded template tags
+     - `{template_name}.css` - Tailwind CSS source
+     - `{template_name}.js` - JavaScript (Alpine.js initialization)
+   - **Output Location**: `microdocs/templates/{template_name}/{template_name}.html`
+     - Single-file HTML with all CSS/JS inlined by Vite
+   - **Default Template** (`templates/default/default.html`):
+     - Single-page HTML template with Tailwind CSS and Alpine.js
+     - Uses CDN for Alpine.js 3.x and Tocbot
+     - Two-column layout:
+       - Main content area (left, flex-1)
+       - TOC sidebar (right, fixed 16rem width, sticky)
+     - Page-based navigation: sections act like pages, only one visible at a time
+     - Alpine.js state: `activeSection` tracks which section is displayed
+     - Smooth transitions between sections
+     - Dynamic navigation with active state highlighting
+     - Table of Contents (TOC):
+       - Shows all headings (H1-H6) for current section
+       - Automatically indented based on heading level
+       - Sticky positioning (follows scroll)
+       - Each section has its own TOC
+   - **Template Variables** (Jinja2):
+     - `{{ title }}` - Extracted from first H1 or provided via CLI
+     - `{{ sections }}` - List of sections with `id`, `name`, `html` attributes
      - `{{ repo_url }}` - Optional repository URL
+     - `{{ build_timestamp }}` - Build timestamp in UTC
 
 ### Important Notes
 

README.md

@@ -110,53 +110,25 @@ Automatically deploy your documentation to GitHub Pages:
 
 ## Template System
 
-Microdocs uses Jinja2 templates. The default template includes:
+Microdocs uses Jinja2 templates with Vite-based builds. The default template includes:
 
 - **Responsive Layout** - Two-column design with main content and TOC sidebar
 - **Page Navigation** - Tab-like navigation between sections
 - **Sticky TOC** - Table of contents that follows you as you scroll
-- **Dark Mode Ready** - Styles work well in light and dark themes
-
-### Template Variables
-
-Your custom templates have access to:
-
-- `{{ title }}` - Document title
-- `{{ sections }}` - List of sections with:
-  - `id` - Section identifier (from filename)
-  - `name` - Section display name
-  - `html` - Converted HTML content
-- `{{ inlined_css }}` - CSS content from companion `.css` file
-- `{{ repo_url }}` - Repository URL (if provided)
-- `{{ build_timestamp }}` - Build timestamp in UTC format
-
-### Creating Custom Templates
-
-1. Create an HTML file with Jinja2 template syntax
-2. Optionally create a companion CSS file (same name with `.css` extension)
-3. Use it with the `--template` option
-
-Example minimal template:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <title>{{ title }}</title>
-    <style>{{ inlined_css }}</style>
-</head>
-<body>
-    <h1>{{ title }}</h1>
-    {% for section in sections %}
-        <section id="{{ section.id }}">
-            <h2>{{ section.name }}</h2>
-            {{ section.html|safe }}
-        </section>
-    {% endfor %}
-</body>
-</html>
+- **Dark Mode Ready** - Automatic theme detection with manual toggle
+
+### Using Custom Templates
+
+```bash
+# Use built-in template by name
+uvx microdocs README.md -t default
+
+# Use custom template file
+uvx microdocs README.md -t /path/to/custom-template.html
 ```
 
+**[See full template development guide →](templates_src/TEMPLATES.md)**
+
 ## File Support
 
 - **Markdown files** (`.md`, `.markdown`) - Full markdown processing with extensions

runtests.sh

@@ -5,3 +5,5 @@ set -euxo pipefail
 for python in 3.{11..14}; do
     uv run --python=${python} --group=dev pytest
 done
+
+npm run test