Skip to content

Commit de1fdf4

Browse files
rjordanrjordan
committed
Rework mcp, and generate static MD files from content.
1 parent 853c7c3 commit de1fdf4

25 files changed

+4954
-103
lines changed

‎.github/workflows/README.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# GitHub Actions for Aetheria Documentation
2+
3+
This directory contains GitHub Actions workflows for automatically generating and releasing the Aetheria world reference documentation.
4+
5+
## Workflows
6+
7+
### 🚀 Release Documentation (`release-docs.yml`)
8+
9+
**Trigger:** Manual workflow dispatch
10+
**Purpose:** Generate documentation and create a versioned GitHub release
11+
12+
#### Usage:
13+
1. Go to **Actions** → **Generate and Release Documentation**
14+
2. Click **Run workflow**
15+
3. Enter a version tag (e.g., `v1.0.0`, `v2.1.0`)
16+
4. Optionally mark as pre-release
17+
5. Click **Run workflow**
18+
19+
#### What it does:
20+
- ✅ Crawls the live GitHub Pages site
21+
- ✅ Generates individual markdown files for each page
22+
- ✅ Validates all required files are created
23+
- ✅ Creates a metadata file with generation details
24+
- ✅ Packages everything into a ZIP archive
25+
- ✅ Creates a GitHub release with detailed description
26+
- ✅ Attaches the ZIP file to the release
27+
28+
#### Output:
29+
- **GitHub Release** with version tag
30+
- **ZIP Archive**: `aetheria-docs-{version}.zip`
31+
- **Release Notes** with file statistics and usage instructions
32+
33+
---
34+
35+
### 🧪 Test Documentation Generation (`test-docs.yml`)
36+
37+
**Trigger:** Manual dispatch or PR changes to crawler/workflows
38+
**Purpose:** Test documentation generation without creating a release
39+
40+
#### Usage:
41+
- **Manual**: Go to **Actions** → **Test Documentation Generation** → **Run workflow**
42+
- **Automatic**: Triggered on PRs that modify the crawler or workflows
43+
44+
#### What it does:
45+
- ✅ Generates documentation from live site
46+
- ✅ Validates file structure and content
47+
- ✅ Checks file sizes and counts
48+
- ✅ Reports statistics and any issues
49+
- ✅ Uploads generated files as artifacts (7-day retention)
50+
51+
#### Output:
52+
- **Artifacts**: Generated markdown files for download/inspection
53+
- **Logs**: Detailed validation and statistics
54+
55+
## Release Process
56+
57+
### Recommended Versioning:
58+
- **Major versions** (v1.0.0, v2.0.0): Significant world updates or structural changes
59+
- **Minor versions** (v1.1.0, v1.2.0): New content, additional pages, or feature improvements
60+
- **Patch versions** (v1.0.1, v1.0.2): Bug fixes, formatting improvements, or small updates
61+
62+
### Example Release Workflow:
63+
1. **Test First**: Run the test workflow to verify generation works
64+
2. **Create Release**: Use the release workflow with appropriate version
65+
3. **Verify**: Check the created release and download/test the ZIP file
66+
4. **Announce**: Share the release link for others to download
67+
68+
## Archive Contents
69+
70+
Each release ZIP contains:
71+
- **README.md** - Master index and navigation
72+
- **Main sections** - Core world documentation (10 files)
73+
- **Subsections** - Detailed pages like magic schools (10+ files)
74+
- **RELEASE_INFO.md** - Generation metadata and usage instructions
75+
76+
## Benefits
77+
78+
### For Users:
79+
- 📦 **Easy Download**: Single ZIP with everything
80+
- 🏷️ **Versioned**: Track changes and updates over time
81+
- 📋 **Complete Index**: Know exactly what's included
82+
- 🤖 **AI Ready**: Optimized for AI model contexts
83+
84+
### For Maintainers:
85+
- 🔄 **Automated**: No manual documentation generation
86+
- ✅ **Validated**: Automatic checks ensure quality
87+
- 📊 **Tracked**: GitHub releases provide download metrics
88+
- 🔗 **Linked**: Direct connection to source commits
89+
90+
## File Structure
91+
92+
```
93+
.github/workflows/
94+
├── release-docs.yml # Main release workflow
95+
├── test-docs.yml # Testing workflow
96+
└── README.md # This documentation
97+
```
98+
99+
## Troubleshooting
100+
101+
### Common Issues:
102+
- **Puppeteer fails**: Usually resolved by the comprehensive dependency installation
103+
- **Missing files**: Check if the live site is accessible and pages are loading
104+
- **Large files**: Verify the crawler isn't including unintended content
105+
- **Permission errors**: Ensure GITHUB_TOKEN has appropriate permissions
106+
107+
### Debugging:
108+
1. Run the test workflow first to identify issues
109+
2. Check the action logs for specific error messages
110+
3. Verify the live GitHub Pages site is functioning
111+
4. Test the crawler locally if needed
112+
113+
## Future Enhancements
114+
115+
Potential improvements:
116+
- **Scheduled releases**: Automatic releases on a schedule
117+
- **Diff reports**: Compare changes between versions
118+
- **Multiple formats**: PDF or HTML generation
119+
- **Notification**: Slack/Discord notifications for new releases
120+
- **CDN upload**: Automatically publish to a CDN

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

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
name: Generate and Release Documentation
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
version:
7+
description: 'Release version (e.g., v1.0.0, v2.1.0)'
8+
required: true
9+
type: string
10+
prerelease:
11+
description: 'Mark as pre-release'
12+
required: false
13+
default: false
14+
type: boolean
15+
16+
jobs:
17+
generate-and-release:
18+
runs-on: ubuntu-latest
19+
20+
steps:
21+
- name: Checkout repository
22+
uses: actions/checkout@v4
23+
24+
- name: Setup Node.js
25+
uses: actions/setup-node@v4
26+
with:
27+
node-version: '20'
28+
cache: 'npm'
29+
cache-dependency-path: site/package-lock.json
30+
31+
- name: Install dependencies
32+
run: |
33+
cd site
34+
npm ci
35+
36+
- name: Install Puppeteer dependencies
37+
run: |
38+
sudo apt-get update
39+
sudo apt-get install -y \
40+
ca-certificates \
41+
fonts-liberation \
42+
libappindicator3-1 \
43+
libasound2 \
44+
libatk-bridge2.0-0 \
45+
libatk1.0-0 \
46+
libc6 \
47+
libcairo2 \
48+
libcups2 \
49+
libdbus-1-3 \
50+
libexpat1 \
51+
libfontconfig1 \
52+
libgbm1 \
53+
libgcc1 \
54+
libglib2.0-0 \
55+
libgtk-3-0 \
56+
libnspr4 \
57+
libnss3 \
58+
libpango-1.0-0 \
59+
libpangocairo-1.0-0 \
60+
libstdc++6 \
61+
libx11-6 \
62+
libx11-xcb1 \
63+
libxcb1 \
64+
libxcomposite1 \
65+
libxcursor1 \
66+
libxdamage1 \
67+
libxext6 \
68+
libxfixes3 \
69+
libxi6 \
70+
libxrandr2 \
71+
libxrender1 \
72+
libxss1 \
73+
libxtst6 \
74+
lsb-release \
75+
wget \
76+
xdg-utils
77+
78+
- name: Generate documentation
79+
run: |
80+
cd site
81+
node crawl-github-pages.js
82+
83+
- name: Validate documentation generation
84+
run: |
85+
cd site/generated-docs
86+
echo "📊 Generated files:"
87+
ls -la
88+
echo ""
89+
echo "📋 File count: $(ls -1 *.md | wc -l)"
90+
echo "📏 Total size: $(du -sh . | cut -f1)"
91+
92+
# Verify required files exist
93+
if [ ! -f "README.md" ]; then
94+
echo "❌ README.md not found!"
95+
exit 1
96+
fi
97+
98+
if [ ! -f "index.md" ]; then
99+
echo "❌ index.md not found!"
100+
exit 1
101+
fi
102+
103+
if [ ! -f "magic.md" ]; then
104+
echo "❌ magic.md not found!"
105+
exit 1
106+
fi
107+
108+
echo "✅ Documentation validation passed!"
109+
110+
- name: Create release archive
111+
run: |
112+
cd site/generated-docs
113+
114+
# Create metadata file
115+
cat > RELEASE_INFO.md << EOF
116+
# Aetheria World Reference - Release ${{ github.event.inputs.version }}
117+
118+
**Generated:** $(date -u '+%Y-%m-%d %H:%M:%S UTC')
119+
**Source Commit:** ${{ github.sha }}
120+
**GitHub Pages Source:** https://rjordan.github.io/Aetheria
121+
**Repository:** https://github.com/${{ github.repository }}
122+
123+
## Contents
124+
125+
This archive contains the complete Aetheria world reference documentation as individual markdown files:
126+
127+
- **README.md** - Master index and usage instructions
128+
- **Main sections** - Core world information (classes, magic, equipment, etc.)
129+
- **Subsections** - Detailed pages (magic schools, specific topics)
130+
131+
## Usage
132+
133+
1. Extract the archive
134+
2. Start with \`README.md\` for the complete index
135+
3. Load individual files into your AI model as needed
136+
4. Use the navigation links to move between related sections
137+
138+
## File Structure
139+
140+
\`\`\`
141+
$(ls -la *.md | awk '{print $9, "(" $5 " bytes)"}' | sort)
142+
\`\`\`
143+
144+
## Total Statistics
145+
146+
- **Files:** $(ls -1 *.md | wc -l) markdown documents
147+
- **Size:** $(du -sh . | cut -f1) uncompressed
148+
- **Words:** ~$(cat *.md | wc -w) total words
149+
150+
For the latest version, visit: https://github.com/${{ github.repository }}/releases
151+
EOF
152+
153+
# Create the release archive
154+
zip -r "aetheria-docs-${{ github.event.inputs.version }}.zip" *.md RELEASE_INFO.md
155+
156+
echo "📦 Created release archive:"
157+
ls -lh *.zip
158+
159+
- name: Create release
160+
uses: softprops/action-gh-release@v1
161+
with:
162+
tag_name: ${{ github.event.inputs.version }}
163+
name: "Aetheria Documentation ${{ github.event.inputs.version }}"
164+
body: |
165+
# Aetheria World Reference Documentation
166+
167+
Complete modular documentation for the Aetheria fantasy world, automatically generated from the live GitHub Pages site.
168+
169+
## What's Included
170+
171+
📋 **${{ steps.count-files.outputs.count }} Markdown Files** - Individual pages for each section
172+
🔗 **Cross-Linked Navigation** - Easy movement between related topics
173+
📖 **Master Index** - Complete overview and usage instructions
174+
🤖 **AI-Optimized** - Perfect for loading into AI model contexts
175+
176+
## Quick Start
177+
178+
1. Download the `aetheria-docs-${{ github.event.inputs.version }}.zip` file below
179+
2. Extract and start with `README.md` for the complete index
180+
3. Load individual sections into your AI model as needed
181+
182+
## File Highlights
183+
184+
- **README.md** - Master index and usage guide
185+
- **magic.md** + **magic-*.md** - Complete magic system with all schools
186+
- **classes.md** - All character classes and abilities
187+
- **politics.md** - Organizations and factions
188+
- **religion.md** - Gods, beliefs, and spiritual practices
189+
190+
## Generated From
191+
192+
- **Source:** https://rjordan.github.io/Aetheria
193+
- **Commit:** ${{ github.sha }}
194+
- **Generated:** $(date -u '+%Y-%m-%d %H:%M:%S UTC')
195+
196+
Perfect for AI storytelling, world-building, and RPG reference!
197+
files: |
198+
site/generated-docs/aetheria-docs-${{ github.event.inputs.version }}.zip
199+
prerelease: ${{ github.event.inputs.prerelease }}
200+
draft: false
201+
env:
202+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
203+
204+
- name: Summary
205+
run: |
206+
echo "🎉 Release ${{ github.event.inputs.version }} created successfully!"
207+
echo "📁 Archive: aetheria-docs-${{ github.event.inputs.version }}.zip"
208+
echo "🔗 View release: https://github.com/${{ github.repository }}/releases/tag/${{ github.event.inputs.version }}"

0 commit comments

Comments
 (0)