Skip to content

Commit 49f7134

Browse files
johnnytclaude
johnnyt
and
claude
authored
Adds VitePress site with Diataxis structure (#96)
* Adds documentation Claude agent * Moves doc agent to markdown doc * Adds VitePress documentation site with Diataxis structure - Sets up VitePress with basic homepage and getting started guide - Creates package.json with VitePress dependencies and npm scripts - Configures GitHub Actions for automatic deployment to GitHub Pages - Separates documentation linting into dedicated lint-docs workflow - Updates docs agent configuration to use Diataxis terminology - Configures deployment for main branch instead of master * Fixes VitePress build by adding ESM module type - Adds 'type: module' to package.json to support VitePress ESM requirements - Resolves build error preventing GitHub Actions from completing --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent f26dfd4 commit 49f7134

12 files changed

Lines changed: 2989 additions & 82 deletions

File tree

‎.claude/agents/docs.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
name: docs
3+
description: Specialized agent for managing Statifier library documentation using the Diataxis documentation system. Expert in SCXML state machines, VitePress, and GitHub Pages deployment.
4+
tools: Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Bash
5+
---
6+
7+
You are a specialized documentation agent for the Statifier SCXML library with expertise in:
8+
9+
## Core Knowledge Areas
10+
11+
### 1. Diataxis Documentation System
12+
13+
- **Tutorials**: Learning-oriented lessons for beginners that guide through completing projects
14+
- **How-to Guides**: Problem-solving oriented step-by-step instructions for specific tasks
15+
- **Reference**: Information-oriented technical documentation describing the system
16+
- **Explanation**: Understanding-oriented content providing deeper context and rationale
17+
18+
### 2. Statifier Library Domain
19+
20+
- SCXML (State Chart XML) W3C specification compliance
21+
- Elixir implementation with GenServer architecture
22+
- State machine concepts: states, transitions, parallel execution, history states
23+
- Core modules: Parser, Validator, Interpreter, StateChart, Configuration
24+
- Test coverage: SCION and W3C test suites
25+
- Current architecture: Parse → Validate → Optimize phases
26+
27+
### 3. Technical Implementation
28+
29+
- **VitePress**: Vue-powered static site generator optimized for technical documentation
30+
- **GitHub Pages**: Free hosting with automatic deployment via GitHub Actions
31+
- **Markdown**: Primary content format with Vue component support
32+
- **Interactive Examples**: Vue components for state machine visualizations
33+
34+
## Agent Capabilities
35+
36+
### Content Analysis & Migration
37+
38+
- Analyze existing documentation (README.md, CLAUDE.md, code comments)
39+
- Categorize content into appropriate Diataxis quadrants
40+
- Identify documentation gaps and opportunities
41+
- Extract and restructure content while preserving technical accuracy
42+
43+
### Documentation Generation
44+
45+
- Create tutorials that guide users through building state machines
46+
- Write how-to guides for specific SCXML implementation tasks
47+
- Generate comprehensive API reference from code
48+
- Develop explanations of state machine concepts and architectural decisions
49+
50+
### VitePress & GitHub Pages Setup
51+
52+
- Configure VitePress for optimal GitHub Pages deployment
53+
- Set up navigation structure following Diataxis principles
54+
- Create GitHub Actions workflows for automated deployment
55+
- Implement search, theming, and responsive design
56+
57+
### Quality Assurance
58+
59+
- Ensure technical accuracy of SCXML and state machine concepts
60+
- Validate code examples and ensure they work with current Statifier API
61+
- Maintain consistency across documentation types
62+
- Follow Elixir and SCXML community conventions
63+
64+
## Response Guidelines
65+
66+
1. **Diataxis Classification**: Always consider which quadrant new content belongs to
67+
2. **Technical Accuracy**: Verify all code examples and technical statements
68+
3. **User Journey**: Consider the reader's knowledge level and goals
69+
4. **Actionable Content**: Provide concrete, testable examples
70+
5. **Cross-References**: Link between quadrants appropriately
71+
72+
## Specialized Tasks
73+
74+
- Migrate existing CLAUDE.md content to structured Diataxis documentation
75+
- Create interactive SCXML examples with state machine visualizations
76+
- Generate API documentation from Elixir modules with @doc annotations
77+
- Develop tutorial series progressing from basic to advanced state machine concepts
78+
- Write how-to guides for common SCXML implementation patterns
79+
- Create explanatory content about W3C SCXML compliance and architectural decisions
80+
81+
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‎

Lines changed: 49 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,60 @@
1-
name: Documentation
1+
name: Deploy Documentation
22

33
on:
44
push:
5-
branches: [ main ]
6-
paths:
7-
- '**/*.md'
8-
- 'CLAUDE.md'
9-
- 'README.md'
10-
- 'docs/**'
5+
branches: [main]
6+
paths: ['docs/**', 'package.json']
117
pull_request:
12-
branches: [ main ]
13-
paths:
14-
- '**/*.md'
15-
- 'CLAUDE.md'
16-
- 'README.md'
17-
- 'docs/**'
8+
branches: [main]
9+
paths: ['docs/**', 'package.json']
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: pages
19+
cancel-in-progress: false
1820

1921
jobs:
20-
lint-docs:
21-
name: Lint Documentation
22+
# Build job
23+
build:
2224
runs-on: ubuntu-latest
23-
2425
steps:
25-
- name: Checkout code
26-
uses: actions/checkout@v4
27-
28-
- name: Lint Markdown files
29-
uses: DavidAnson/markdownlint-cli2-action@v13
30-
with:
31-
globs: |
32-
**/*.md
33-
!node_modules/**/*.md
34-
35-
- name: Check for broken links
36-
uses: gaurav-nelson/github-action-markdown-link-check@v1
37-
with:
38-
use-quiet-mode: 'yes'
39-
use-verbose-mode: 'yes'
40-
config-file: '.github/workflows/markdown-link-check-config.json'
41-
42-
validate-memory:
43-
name: Validate Memory Files
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0
30+
31+
- name: Setup Node.js
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version: 20
35+
cache: npm
36+
37+
- name: Install dependencies
38+
run: npm ci
39+
40+
- name: Build with VitePress
41+
run: npm run docs:build
42+
43+
- name: Upload artifact
44+
uses: actions/upload-pages-artifact@v3
45+
with:
46+
path: docs/.vitepress/dist
47+
48+
# Deployment job
49+
deploy:
50+
if: github.ref == 'refs/heads/main'
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
needs: build
4455
runs-on: ubuntu-latest
45-
4656
steps:
47-
- name: Checkout code
48-
uses: actions/checkout@v4
49-
50-
- name: Check CLAUDE.md structure
51-
run: |
52-
echo "Validating CLAUDE.md structure..."
53-
if ! grep -q "## Commands" CLAUDE.md; then
54-
echo "❌ CLAUDE.md missing Commands section"
55-
exit 1
56-
fi
57-
if ! grep -q "## Architecture" CLAUDE.md; then
58-
echo "❌ CLAUDE.md missing Architecture section"
59-
exit 1
60-
fi
61-
echo "✅ CLAUDE.md structure looks good"
62-
63-
- name: Check README.md structure
64-
run: |
65-
echo "Validating README.md structure..."
66-
if ! grep -q "## Features" README.md; then
67-
echo "❌ README.md missing Features section"
68-
exit 1
69-
fi
70-
if ! grep -q "## Current Status" README.md; then
71-
echo "❌ README.md missing Current Status section"
72-
exit 1
73-
fi
74-
echo "✅ README.md structure looks good"
57+
- name: Deploy to GitHub Pages
58+
id: deployment
59+
uses: actions/deploy-pages@v4
7560

76-
- name: Validate documentation consistency
77-
run: |
78-
echo "Checking for API consistency between CLAUDE.md and README.md..."
79-
80-
# Check that both files reference Statifier.Validator (not Statifier.Document.Validator)
81-
if grep -q "Statifier\.Document\.Validator" CLAUDE.md README.md; then
82-
echo "❌ Found outdated Statifier.Document.Validator references - should be Statifier.Validator"
83-
grep -n "Statifier\.Document\.Validator" CLAUDE.md README.md || true
84-
exit 1
85-
fi
86-
87-
echo "✅ API references look consistent"

‎.github/workflows/lint-docs.yml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
name: Lint Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- '**/*.md'
8+
- '.github/workflows/lint-docs.yml'
9+
pull_request:
10+
branches: [main]
11+
paths:
12+
- '**/*.md'
13+
- '.github/workflows/lint-docs.yml'
14+
15+
jobs:
16+
lint-docs:
17+
name: Lint Documentation
18+
runs-on: ubuntu-latest
19+
20+
steps:
21+
- name: Checkout code
22+
uses: actions/checkout@v4
23+
24+
- name: Lint Markdown files
25+
uses: DavidAnson/markdownlint-cli2-action@v13
26+
with:
27+
globs: |
28+
**/*.md
29+
!node_modules/**/*.md
30+
!docs/.vitepress/dist/**/*.md
31+
32+
# - name: Check for broken links
33+
# uses: gaurav-nelson/github-action-markdown-link-check@v1
34+
# with:
35+
# use-quiet-mode: 'yes'
36+
# use-verbose-mode: 'yes'
37+
# config-file: '.github/workflows/markdown-link-check-config.json'
38+
39+
validate-memory:
40+
name: Validate Memory Files
41+
runs-on: ubuntu-latest
42+
43+
steps:
44+
- name: Checkout code
45+
uses: actions/checkout@v4
46+
47+
- name: Check CLAUDE.md structure
48+
run: |
49+
echo "Validating CLAUDE.md structure..."
50+
if ! grep -q "## Commands" CLAUDE.md; then
51+
echo "❌ CLAUDE.md missing Commands section"
52+
exit 1
53+
fi
54+
if ! grep -q "## Architecture" CLAUDE.md; then
55+
echo "❌ CLAUDE.md missing Architecture section"
56+
exit 1
57+
fi
58+
echo "✅ CLAUDE.md structure looks good"
59+
60+
- name: Check README.md structure
61+
run: |
62+
echo "Validating README.md structure..."
63+
if ! grep -q "## Features" README.md; then
64+
echo "❌ README.md missing Features section"
65+
exit 1
66+
fi
67+
if ! grep -q "## Current Status" README.md; then
68+
echo "❌ README.md missing Current Status section"
69+
exit 1
70+
fi
71+
echo "✅ README.md structure looks good"
72+
73+
- name: Validate documentation consistency
74+
run: |
75+
echo "Checking for API consistency between CLAUDE.md and README.md..."
76+
77+
# Check that both files reference Statifier.Validator (not Statifier.Document.Validator)
78+
if grep -q "Statifier\.Document\.Validator" CLAUDE.md README.md; then
79+
echo "❌ Found outdated Statifier.Document.Validator references - should be Statifier.Validator"
80+
grep -n "Statifier\.Document\.Validator" CLAUDE.md README.md || true
81+
exit 1
82+
fi
83+
84+
echo "✅ API references look consistent"

‎.gitignore‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ erl_crash.dump
1616
# Also ignore archive artifacts (built via "mix archive.build").
1717
*.ez
1818

19+
# Node dependencies for building docs
20+
/node_modules
21+
22+
# Generated docs site
23+
/docs/.vitepress/dist
24+
1925
# Ignore package tarball (built via "mix hex.build").
2026
statifier-*.tar
2127

@@ -29,4 +35,4 @@ statifier-*.tar
2935
/priv/plts/
3036

3137
# Keep granted permissions local to the person
32-
.claude
38+
.claude/*.local.json

‎.markdownlint.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
{
22
"default": true,
3+
"gitignore": true,
4+
"ignores": [
5+
"node_modules/"
6+
],
37
"line-length": false,
48
"no-duplicate-heading": false,
59
"no-inline-html": {

‎docs/.vitepress/config.js‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
export default defineConfig({
4+
title: 'Statifier Documentation',
5+
description: 'SCXML State Machines for Elixir - Complete W3C compliant implementation',
6+
base: '/statifier/',
7+
8+
head: [
9+
['link', { rel: 'icon', href: '/statifier/favicon.ico' }],
10+
['meta', { name: 'theme-color', content: '#6b46c1' }]
11+
],
12+
13+
themeConfig: {
14+
logo: '/logo.svg',
15+
16+
nav: [
17+
{ text: 'Home', link: '/' },
18+
{ text: 'Get Started', link: '/getting-started' },
19+
{
20+
text: 'Links',
21+
items: [
22+
{ text: 'GitHub', link: 'https://github.com/riddler/statifier' },
23+
{ text: 'Hex Package', link: 'https://hex.pm/packages/statifier' },
24+
{ text: 'Hex Docs', link: 'https://hexdocs.pm/statifier/' }
25+
]
26+
}
27+
],
28+
29+
sidebar: [
30+
{
31+
text: 'Introduction',
32+
items: [
33+
{ text: 'What is Statifier?', link: '/' },
34+
{ text: 'Getting Started', link: '/getting-started' }
35+
]
36+
}
37+
],
38+
39+
socialLinks: [
40+
{ icon: 'github', link: 'https://github.com/riddler/statifier' }
41+
],
42+
43+
footer: {
44+
message: 'Released under the MIT License.',
45+
copyright: 'Copyright © 2024 Riddler'
46+
},
47+
48+
search: {
49+
provider: 'local'
50+
},
51+
52+
editLink: {
53+
pattern: 'https://github.com/riddler/statifier/edit/main/docs/:path',
54+
text: 'Edit this page on GitHub'
55+
}
56+
},
57+
58+
markdown: {
59+
theme: 'github-dark',
60+
lineNumbers: true
61+
}
62+
})

0 commit comments

Comments
 (0)