Adds VitePress docs site with Diataxis structure

.claude/agents/docs.md

@@ -0,0 +1,81 @@
+---
+name: docs
+description: Specialized agent for managing Statifier library documentation using the Diataxis documentation system. Expert in SCXML state machines, VitePress, and GitHub Pages deployment.
+tools: Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Bash
+---
+
+You are a specialized documentation agent for the Statifier SCXML library with expertise in:
+
+## Core Knowledge Areas
+
+### 1. Diataxis Documentation System
+
+- **Tutorials**: Learning-oriented lessons for beginners that guide through completing projects
+- **How-to Guides**: Problem-solving oriented step-by-step instructions for specific tasks
+- **Reference**: Information-oriented technical documentation describing the system
+- **Explanation**: Understanding-oriented content providing deeper context and rationale
+
+### 2. Statifier Library Domain
+
+- SCXML (State Chart XML) W3C specification compliance
+- Elixir implementation with GenServer architecture
+- State machine concepts: states, transitions, parallel execution, history states
+- Core modules: Parser, Validator, Interpreter, StateChart, Configuration
+- Test coverage: SCION and W3C test suites
+- Current architecture: Parse → Validate → Optimize phases
+
+### 3. Technical Implementation
+
+- **VitePress**: Vue-powered static site generator optimized for technical documentation
+- **GitHub Pages**: Free hosting with automatic deployment via GitHub Actions
+- **Markdown**: Primary content format with Vue component support
+- **Interactive Examples**: Vue components for state machine visualizations
+
+## Agent Capabilities
+
+### Content Analysis & Migration
+
+- Analyze existing documentation (README.md, CLAUDE.md, code comments)
+- Categorize content into appropriate Diataxis quadrants
+- Identify documentation gaps and opportunities
+- Extract and restructure content while preserving technical accuracy
+
+### Documentation Generation
+
+- Create tutorials that guide users through building state machines
+- Write how-to guides for specific SCXML implementation tasks
+- Generate comprehensive API reference from code
+- Develop explanations of state machine concepts and architectural decisions
+
+### VitePress & GitHub Pages Setup
+
+- Configure VitePress for optimal GitHub Pages deployment
+- Set up navigation structure following Diataxis principles
+- Create GitHub Actions workflows for automated deployment
+- Implement search, theming, and responsive design
+
+### Quality Assurance
+
+- Ensure technical accuracy of SCXML and state machine concepts
+- Validate code examples and ensure they work with current Statifier API
+- Maintain consistency across documentation types
+- Follow Elixir and SCXML community conventions
+
+## Response Guidelines
+
+1. **Diataxis Classification**: Always consider which quadrant new content belongs to
+2. **Technical Accuracy**: Verify all code examples and technical statements
+3. **User Journey**: Consider the reader's knowledge level and goals
+4. **Actionable Content**: Provide concrete, testable examples
+5. **Cross-References**: Link between quadrants appropriately
+
+## Specialized Tasks
+
+- Migrate existing CLAUDE.md content to structured Diataxis documentation
+- Create interactive SCXML examples with state machine visualizations
+- Generate API documentation from Elixir modules with @doc annotations
+- Develop tutorial series progressing from basic to advanced state machine concepts
+- Write how-to guides for common SCXML implementation patterns
+- Create explanatory content about W3C SCXML compliance and architectural decisions
+
+When working on documentation tasks, always consider the four Diataxis quadrants and ensure content serves its intended purpose within the documentation ecosystem.

.github/workflows/docs.yml

@@ -1,87 +1,60 @@
-name: Documentation
+name: Deploy Documentation
 
 on:
   push:
-    branches: [ main ]
-    paths:
-      - '**/*.md'
-      - 'CLAUDE.md'
-      - 'README.md'
-      - 'docs/**'
+    branches: [main]
+    paths: ['docs/**', 'package.json']
   pull_request:
-    branches: [ main ]
-    paths:
-      - '**/*.md'
-      - 'CLAUDE.md'
-      - 'README.md'
-      - 'docs/**'
+    branches: [main] 
+    paths: ['docs/**', 'package.json']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
-  lint-docs:
-    name: Lint Documentation
+  # Build job
+  build:
     runs-on: ubuntu-latest
-
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-
-    - name: Lint Markdown files
-      uses: DavidAnson/markdownlint-cli2-action@v13
-      with:
-        globs: |
-          **/*.md
-          !node_modules/**/*.md
-
-    - name: Check for broken links
-      uses: gaurav-nelson/github-action-markdown-link-check@v1
-      with:
-        use-quiet-mode: 'yes'
-        use-verbose-mode: 'yes'
-        config-file: '.github/workflows/markdown-link-check-config.json'
-
-  validate-memory:
-    name: Validate Memory Files
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build with VitePress
+        run: npm run docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
     runs-on: ubuntu-latest
-
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-
-    - name: Check CLAUDE.md structure
-      run: |
-        echo "Validating CLAUDE.md structure..."
-        if ! grep -q "## Commands" CLAUDE.md; then
-          echo "❌ CLAUDE.md missing Commands section"
-          exit 1
-        fi
-        if ! grep -q "## Architecture" CLAUDE.md; then
-          echo "❌ CLAUDE.md missing Architecture section"
-          exit 1
-        fi
-        echo "✅ CLAUDE.md structure looks good"
-
-    - name: Check README.md structure
-      run: |
-        echo "Validating README.md structure..."
-        if ! grep -q "## Features" README.md; then
-          echo "❌ README.md missing Features section"
-          exit 1
-        fi
-        if ! grep -q "## Current Status" README.md; then
-          echo "❌ README.md missing Current Status section"
-          exit 1
-        fi
-        echo "✅ README.md structure looks good"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
 
-    - name: Validate documentation consistency
-      run: |
-        echo "Checking for API consistency between CLAUDE.md and README.md..."
-
-        # Check that both files reference Statifier.Validator (not Statifier.Document.Validator)
-        if grep -q "Statifier\.Document\.Validator" CLAUDE.md README.md; then
-          echo "❌ Found outdated Statifier.Document.Validator references - should be Statifier.Validator"
-          grep -n "Statifier\.Document\.Validator" CLAUDE.md README.md || true
-          exit 1
-        fi
-
-        echo "✅ API references look consistent"

.github/workflows/lint-docs.yml

@@ -0,0 +1,84 @@
+name: Lint Documentation
+
+on:
+  push:
+    branches: [main]
+    paths: 
+      - '**/*.md'
+      - '.github/workflows/lint-docs.yml'
+  pull_request:
+    branches: [main]
+    paths: 
+      - '**/*.md'
+      - '.github/workflows/lint-docs.yml'
+
+jobs:
+  lint-docs:
+    name: Lint Documentation
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Lint Markdown files
+      uses: DavidAnson/markdownlint-cli2-action@v13
+      with:
+        globs: |
+          **/*.md
+          !node_modules/**/*.md
+          !docs/.vitepress/dist/**/*.md
+
+    # - name: Check for broken links
+    #   uses: gaurav-nelson/github-action-markdown-link-check@v1
+    #   with:
+    #     use-quiet-mode: 'yes'
+    #     use-verbose-mode: 'yes'
+    #     config-file: '.github/workflows/markdown-link-check-config.json'
+
+  validate-memory:
+    name: Validate Memory Files
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Check CLAUDE.md structure
+      run: |
+        echo "Validating CLAUDE.md structure..."
+        if ! grep -q "## Commands" CLAUDE.md; then
+          echo "❌ CLAUDE.md missing Commands section"
+          exit 1
+        fi
+        if ! grep -q "## Architecture" CLAUDE.md; then
+          echo "❌ CLAUDE.md missing Architecture section"  
+          exit 1
+        fi
+        echo "✅ CLAUDE.md structure looks good"
+
+    - name: Check README.md structure
+      run: |
+        echo "Validating README.md structure..."
+        if ! grep -q "## Features" README.md; then
+          echo "❌ README.md missing Features section"
+          exit 1
+        fi
+        if ! grep -q "## Current Status" README.md; then
+          echo "❌ README.md missing Current Status section"
+          exit 1
+        fi
+        echo "✅ README.md structure looks good"
+
+    - name: Validate documentation consistency
+      run: |
+        echo "Checking for API consistency between CLAUDE.md and README.md..."
+
+        # Check that both files reference Statifier.Validator (not Statifier.Document.Validator)
+        if grep -q "Statifier\.Document\.Validator" CLAUDE.md README.md; then
+          echo "❌ Found outdated Statifier.Document.Validator references - should be Statifier.Validator"
+          grep -n "Statifier\.Document\.Validator" CLAUDE.md README.md || true
+          exit 1
+        fi
+
+        echo "✅ API references look consistent"

.gitignore

@@ -16,6 +16,12 @@ erl_crash.dump
 # Also ignore archive artifacts (built via "mix archive.build").
 *.ez
 
+# Node dependencies for building docs
+/node_modules
+
+# Generated docs site
+/docs/.vitepress/dist
+
 # Ignore package tarball (built via "mix hex.build").
 statifier-*.tar
 
@@ -29,4 +35,4 @@ statifier-*.tar
 /priv/plts/
 
 # Keep granted permissions local to the person
-.claude
+.claude/*.local.json

.markdownlint.json

@@ -1,5 +1,9 @@
 {
   "default": true,
+  "gitignore": true,
+  "ignores": [
+    "node_modules/"
+  ],
   "line-length": false,
   "no-duplicate-heading": false,
   "no-inline-html": {

docs/.vitepress/config.js

@@ -0,0 +1,62 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'Statifier Documentation',
+  description: 'SCXML State Machines for Elixir - Complete W3C compliant implementation',
+  base: '/statifier/',
+
+  head: [
+    ['link', { rel: 'icon', href: '/statifier/favicon.ico' }],
+    ['meta', { name: 'theme-color', content: '#6b46c1' }]
+  ],
+
+  themeConfig: {
+    logo: '/logo.svg',
+
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Get Started', link: '/getting-started' },
+      { 
+        text: 'Links', 
+        items: [
+          { text: 'GitHub', link: 'https://github.com/riddler/statifier' },
+          { text: 'Hex Package', link: 'https://hex.pm/packages/statifier' },
+          { text: 'Hex Docs', link: 'https://hexdocs.pm/statifier/' }
+        ] 
+      }
+    ],
+
+    sidebar: [
+      {
+        text: 'Introduction',
+        items: [
+          { text: 'What is Statifier?', link: '/' },
+          { text: 'Getting Started', link: '/getting-started' }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/riddler/statifier' }
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2024 Riddler'
+    },
+
+    search: {
+      provider: 'local'
+    },
+
+    editLink: {
+      pattern: 'https://github.com/riddler/statifier/edit/main/docs/:path',
+      text: 'Edit this page on GitHub'
+    }
+  },
+
+  markdown: {
+    theme: 'github-dark',
+    lineNumbers: true
+  }
+})