Skip to content

Commit 0808794

Browse files
salacosteclaude
salacoste
and
claude
committed
docs: complete Epic 8 troubleshooting, FAQ, and contributing documentation
Add comprehensive documentation for GitHub Pages deployment including: Epic 8 - Deployment & Publishing: - GitHub Pages deployment guide with CI/CD workflows - Automated validation workflow for pull requests - Pre-deployment validation checklist - Performance optimization guide Epic 8 - Troubleshooting & Support: - Error reference with categorized solutions - Debug mode and logging guide - Testing infrastructure documentation - FAQ with 30+ common questions - Contributing guidelines for developers - Version compatibility and migration guide Documentation Infrastructure: - MkDocs Material configuration - 38 comprehensive documentation pages - 6 major navigation sections - Automated deployment via GitHub Actions - Build validation and quality gates Total: ~150,000+ words of technical documentation Deployment URL: https://salacoste.github.io/mcp-n8n-workflow-builder 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 256b539 commit 0808794

154 files changed

Lines changed: 81696 additions & 7 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.eslintignore‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
build/
6+
dist/
7+
8+
# Documentation (MkDocs)
9+
docs/
10+
site/
11+
12+
# Test coverage
13+
coverage/
14+
15+
# Temporary files
16+
*.log
17+
.env
18+
.config.json

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- 'mkdocs.yml'
10+
- '.github/workflows/deploy-docs.yml'
11+
- 'requirements.txt'
12+
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: write
17+
pages: write
18+
id-token: write
19+
20+
# Allow one concurrent deployment
21+
concurrency:
22+
group: "pages"
23+
cancel-in-progress: true
24+
25+
jobs:
26+
deploy:
27+
runs-on: ubuntu-latest
28+
29+
steps:
30+
- name: Checkout repository
31+
uses: actions/checkout@v4
32+
with:
33+
fetch-depth: 0 # Full history for git-revision-date plugin
34+
35+
- name: Setup Python
36+
uses: actions/setup-python@v4
37+
with:
38+
python-version: '3.11'
39+
cache: 'pip'
40+
41+
- name: Install dependencies
42+
run: |
43+
pip install --upgrade pip
44+
pip install -r requirements.txt
45+
46+
- name: Configure Git
47+
run: |
48+
git config user.name "github-actions[bot]"
49+
git config user.email "github-actions[bot]@users.noreply.github.com"
50+
51+
- name: Build documentation
52+
run: |
53+
mkdocs build --strict --verbose
54+
55+
- name: Upload artifact
56+
uses: actions/upload-pages-artifact@v2
57+
with:
58+
path: ./site
59+
60+
- name: Deploy to GitHub Pages
61+
id: deployment
62+
uses: actions/deploy-pages@v2
63+
64+
- name: Deployment Summary
65+
run: |
66+
echo "## Documentation Deployment Complete! :rocket:" >> $GITHUB_STEP_SUMMARY
67+
echo "" >> $GITHUB_STEP_SUMMARY
68+
echo "- **Build Status:** ✅ Success" >> $GITHUB_STEP_SUMMARY
69+
echo "- **Deployment URL:** https://salacoste.github.io/mcp-n8n-workflow-builder" >> $GITHUB_STEP_SUMMARY
70+
echo "- **Commit SHA:** ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
71+
echo "- **Timestamp:** $(date -u +'%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_STEP_SUMMARY

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

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
name: Validate Documentation
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- 'mkdocs.yml'
10+
- 'requirements.txt'
11+
- '.github/workflows/validate-docs.yml'
12+
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: read
17+
pull-requests: write
18+
19+
jobs:
20+
validate:
21+
runs-on: ubuntu-latest
22+
timeout-minutes: 10
23+
24+
steps:
25+
- name: Checkout repository
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0 # Full history for git-revision-date plugin
29+
30+
- name: Setup Python
31+
uses: actions/setup-python@v4
32+
with:
33+
python-version: '3.11'
34+
cache: 'pip'
35+
36+
- name: Install dependencies
37+
run: |
38+
pip install --upgrade pip
39+
pip install -r requirements.txt
40+
41+
- name: Validate build (strict mode)
42+
id: build
43+
run: |
44+
echo "::group::Building documentation with strict mode"
45+
mkdocs build --strict --verbose
46+
echo "::endgroup::"
47+
48+
echo "build_status=✅ Success" >> $GITHUB_OUTPUT
49+
50+
- name: Check for warnings
51+
id: warnings
52+
run: |
53+
echo "::group::Checking for build warnings"
54+
WARNINGS=$(mkdocs build --strict 2>&1 | grep -i "warning" | wc -l)
55+
56+
if [ "$WARNINGS" -eq 0 ]; then
57+
echo "warnings_status=✅ No warnings found" >> $GITHUB_OUTPUT
58+
echo "No warnings detected"
59+
else
60+
echo "warnings_status=⚠️ $WARNINGS warning(s) found" >> $GITHUB_OUTPUT
61+
echo "::warning::Found $WARNINGS warning(s) in documentation build"
62+
mkdocs build --strict 2>&1 | grep -i "warning"
63+
fi
64+
echo "::endgroup::"
65+
66+
- name: Check for TODO/FIXME markers
67+
id: todos
68+
continue-on-error: true
69+
run: |
70+
echo "::group::Checking for TODO/FIXME markers"
71+
TODO_COUNT=$(grep -r "TODO\|FIXME\|XXX" docs/ | wc -l || echo "0")
72+
73+
if [ "$TODO_COUNT" -eq 0 ]; then
74+
echo "todos_status=✅ No TODO markers found" >> $GITHUB_OUTPUT
75+
echo "No TODO/FIXME markers detected"
76+
else
77+
echo "todos_status=ℹ️ $TODO_COUNT TODO marker(s) found" >> $GITHUB_OUTPUT
78+
echo "::notice::Found $TODO_COUNT TODO/FIXME marker(s) in documentation"
79+
grep -rn "TODO\|FIXME\|XXX" docs/ | head -10
80+
fi
81+
echo "::endgroup::"
82+
83+
- name: Validate site size
84+
id: size
85+
run: |
86+
echo "::group::Checking site size"
87+
SITE_SIZE=$(du -sh site/ | cut -f1)
88+
SITE_SIZE_BYTES=$(du -sb site/ | cut -f1)
89+
90+
echo "Total site size: $SITE_SIZE"
91+
92+
if [ "$SITE_SIZE_BYTES" -gt 52428800 ]; then
93+
echo "size_status=⚠️ Site size: $SITE_SIZE (exceeds 50MB recommendation)" >> $GITHUB_OUTPUT
94+
echo "::warning::Site size $SITE_SIZE exceeds 50MB recommendation"
95+
else
96+
echo "size_status=✅ Site size: $SITE_SIZE" >> $GITHUB_OUTPUT
97+
fi
98+
echo "::endgroup::"
99+
100+
- name: Check large files
101+
id: large_files
102+
run: |
103+
echo "::group::Checking for large files (>200KB)"
104+
LARGE_FILES=$(find site -type f -size +200k | wc -l)
105+
106+
if [ "$LARGE_FILES" -eq 0 ]; then
107+
echo "large_files_status=✅ No large files found" >> $GITHUB_OUTPUT
108+
else
109+
echo "large_files_status=⚠️ $LARGE_FILES file(s) larger than 200KB" >> $GITHUB_OUTPUT
110+
echo "::warning::Found $LARGE_FILES file(s) larger than 200KB"
111+
echo "Largest files:"
112+
find site -type f -exec du -h {} + | sort -rh | head -10
113+
fi
114+
echo "::endgroup::"
115+
116+
- name: Validate navigation structure
117+
id: navigation
118+
run: |
119+
echo "::group::Validating navigation structure"
120+
121+
# Check if all files in mkdocs.yml exist
122+
python3 << 'EOF'
123+
import yaml
124+
import os
125+
import sys
126+
127+
with open('mkdocs.yml', 'r') as f:
128+
config = yaml.safe_load(f)
129+
130+
missing_files = []
131+
132+
def check_nav_items(items, prefix=''):
133+
for item in items:
134+
if isinstance(item, dict):
135+
for key, value in item.items():
136+
if isinstance(value, str):
137+
# It's a file reference
138+
file_path = os.path.join('docs', value)
139+
if not os.path.exists(file_path):
140+
missing_files.append(value)
141+
elif isinstance(value, list):
142+
# It's a nested structure
143+
check_nav_items(value, prefix + key + ' > ')
144+
145+
if 'nav' in config:
146+
check_nav_items(config['nav'])
147+
148+
if missing_files:
149+
print(f"::error::Missing files referenced in navigation: {', '.join(missing_files)}")
150+
sys.exit(1)
151+
else:
152+
print("✅ All navigation files exist")
153+
EOF
154+
155+
echo "navigation_status=✅ Navigation structure valid" >> $GITHUB_OUTPUT
156+
echo "::endgroup::"
157+
158+
- name: Generate validation summary
159+
if: always()
160+
run: |
161+
echo "## Documentation Validation Summary :clipboard:" >> $GITHUB_STEP_SUMMARY
162+
echo "" >> $GITHUB_STEP_SUMMARY
163+
echo "### Build Validation" >> $GITHUB_STEP_SUMMARY
164+
echo "" >> $GITHUB_STEP_SUMMARY
165+
echo "| Check | Status |" >> $GITHUB_STEP_SUMMARY
166+
echo "|-------|--------|" >> $GITHUB_STEP_SUMMARY
167+
echo "| Build (strict mode) | ${{ steps.build.outputs.build_status || '❌ Failed' }} |" >> $GITHUB_STEP_SUMMARY
168+
echo "| Warnings | ${{ steps.warnings.outputs.warnings_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
169+
echo "| TODO markers | ${{ steps.todos.outputs.todos_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
170+
echo "| Site size | ${{ steps.size.outputs.size_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
171+
echo "| Large files | ${{ steps.large_files.outputs.large_files_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
172+
echo "| Navigation | ${{ steps.navigation.outputs.navigation_status || 'N/A' }} |" >> $GITHUB_STEP_SUMMARY
173+
echo "" >> $GITHUB_STEP_SUMMARY
174+
echo "### Next Steps" >> $GITHUB_STEP_SUMMARY
175+
echo "" >> $GITHUB_STEP_SUMMARY
176+
echo "- Review validation results above" >> $GITHUB_STEP_SUMMARY
177+
echo "- Fix any errors or warnings before merging" >> $GITHUB_STEP_SUMMARY
178+
echo "- Consider optimizing large files if found" >> $GITHUB_STEP_SUMMARY
179+
echo "- Ensure all TODO markers are addressed or documented" >> $GITHUB_STEP_SUMMARY
180+
181+
- name: Comment PR
182+
if: github.event_name == 'pull_request'
183+
uses: actions/github-script@v7
184+
with:
185+
script: |
186+
const buildStatus = '${{ steps.build.outputs.build_status || '❌ Failed' }}';
187+
const warningsStatus = '${{ steps.warnings.outputs.warnings_status || 'N/A' }}';
188+
const todosStatus = '${{ steps.todos.outputs.todos_status || 'N/A' }}';
189+
const sizeStatus = '${{ steps.size.outputs.size_status || 'N/A' }}';
190+
const largeFilesStatus = '${{ steps.large_files.outputs.large_files_status || 'N/A' }}';
191+
const navigationStatus = '${{ steps.navigation.outputs.navigation_status || 'N/A' }}';
192+
193+
const comment = `## Documentation Validation Results :clipboard:
194+
195+
### Build Validation
196+
197+
| Check | Status |
198+
|-------|--------|
199+
| Build (strict mode) | ${buildStatus} |
200+
| Warnings | ${warningsStatus} |
201+
| TODO markers | ${todosStatus} |
202+
| Site size | ${sizeStatus} |
203+
| Large files | ${largeFilesStatus} |
204+
| Navigation | ${navigationStatus} |
205+
206+
### Recommendations
207+
208+
${buildStatus.includes('❌') ? '- ⚠️ **Fix build errors before merging**\n' : ''}
209+
${warningsStatus.includes('⚠️') ? '- 💡 Consider addressing build warnings\n' : ''}
210+
${sizeStatus.includes('⚠️') ? '- 💡 Consider optimizing site size (currently exceeds 50MB)\n' : ''}
211+
${largeFilesStatus.includes('⚠️') ? '- 💡 Consider optimizing large files (>200KB)\n' : ''}
212+
${todosStatus.includes('ℹ️') ? '- ℹ️ TODO markers found - ensure they are documented\n' : ''}
213+
214+
---
215+
*This validation runs automatically on documentation changes*`;
216+
217+
github.rest.issues.createComment({
218+
issue_number: context.issue.number,
219+
owner: context.repo.owner,
220+
repo: context.repo.repo,
221+
body: comment
222+
});

‎docs/.pages‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# MkDocs page ordering configuration
2+
# This file helps organize the navigation structure
3+
4+
nav:
5+
- Home: index.md
6+
- Getting Started:
7+
- Installation:
8+
- npm-installation.md
9+
- manual-installation.md
10+
- configuration.md
11+
- Quick Start:
12+
- claude-desktop.md
13+
- first-workflow.md
14+
- verification.md

0 commit comments

Comments
 (0)