Skip to content

Commit 451a4cf

Browse files
Rayder-23Rayder-23
committed
add: reusable intelligence
1 parent 3f1eae8 commit 451a4cf

21 files changed

Lines changed: 5890 additions & 0 deletions

File tree

‎.claude/agents/spec-architect.md‎

Lines changed: 778 additions & 0 deletions
Large diffs are not rendered by default.

‎.claude/settings.local.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(python:*)",
5+
"Bash(.specify/scripts/bash/create-new-feature.sh:*)",
6+
"Bash(cat:*)",
7+
"Bash(.specify/scripts/bash/setup-plan.sh:*)"
8+
],
9+
"deny": [],
10+
"ask": []
11+
},
12+
"disabledMcpjsonServers": [
13+
],
14+
"enableAllProjectMcpServers": true,
15+
"alwaysThinkingEnabled": false
16+
}

‎.claude/skills/docusaurus-deployer/SKILL.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
name: docusaurus-deployer
3+
version: 1.2
4+
description: This skill should be used when deploying a Docusaurus site to GitHub Pages. It automates the configuration, building, and deployment process, handling GitHub Pages setup, environment configuration, and CI/CD automation. Includes local validation before GitHub Actions triggering.
5+
constitution_alignment: v4.0.1
6+
---
7+
8+
# Docusaurus GitHub Pages Deployer
9+
10+
Automate building and deploying Docusaurus documentation sites to GitHub Pages with local validation before CI/CD triggering.
11+
12+
**Constitution Alignment**: This skill implements production deployment standards defined in Constitution v4.0.1 (Pillar 9: Universal Cloud-Native Deployment from Section I). All deployments must meet project quality gates before publication.
13+
14+
## What This Skill Does
15+
16+
1. **Project Analysis** - Examine Docusaurus structure and dependencies
17+
2. **Local Configuration Validation** - Verify Docusaurus config and sidebars
18+
3. **Local Build & Testing** - Build site locally and validate output
19+
4. **Content Verification** - Check for broken links and syntax errors
20+
5. **GitHub Pages Setup** - Configure repository and deployment settings
21+
6. **CI/CD Automation** - Set up GitHub Actions workflows
22+
7. **Deployment Verification** - Validate successful deployment
23+
24+
## When to Use This Skill
25+
26+
Deploy Docusaurus to GitHub Pages when:
27+
- Setting up documentation deployment for the first time
28+
- Making updates to documentation before publishing
29+
- Updating deployment configuration
30+
- Troubleshooting deployment issues
31+
- Managing multiple documentation sites
32+
- Ensuring documentation quality before production
33+
34+
## How to Use This Skill
35+
36+
Follow the **validate-locally-then-publish** workflow:
37+
38+
### Step 1: Prepare Repository Configuration
39+
Gather GitHub organization/username, repository name, deployment target (user/project pages), and custom domain (optional).
40+
41+
### Step 2: Analyze Project Structure
42+
Examine Docusaurus project:
43+
```bash
44+
ls -la path_to_docusaurus_project/
45+
cat path_to_docusaurus_project/docusaurus.config.ts
46+
cat path_to_docusaurus_project/sidebars.ts
47+
```
48+
49+
Verify docusaurus.config.ts, sidebars.js/ts, package.json engines field, and dependencies exist.
50+
51+
For detailed configuration guidance, see `references/configuration-guide.md`.
52+
53+
### Step 3: Update Docusaurus Configuration
54+
Update `docusaurus.config.ts` with GitHub Pages settings. See `references/configuration-guide.md` for complete configuration examples and guidelines based on deployment target (user vs. project pages).
55+
56+
### Step 4: Build and Validate Locally
57+
Install dependencies, run type checking, build site, validate output, test locally, and verify content quality.
58+
59+
Execute:
60+
```bash
61+
npm ci
62+
npm run typecheck
63+
npm run build
64+
npm run serve
65+
```
66+
67+
For detailed validation procedures, see `references/local-validation-guide.md`.
68+
69+
### Step 5: Commit and Push to Main
70+
After successful local validation:
71+
```bash
72+
git add .
73+
git commit -m "Update documentation: [description]"
74+
git push origin main
75+
```
76+
77+
This triggers the GitHub Actions workflow.
78+
79+
### Step 6: Set Up GitHub Actions
80+
Create `.github/workflows/deploy.yml` using the template in `references/deploy-workflow.yml`.
81+
82+
For detailed workflow configuration and troubleshooting, see `references/github-actions-guide.md`.
83+
84+
### Step 7: Configure GitHub Pages in Repository Settings
85+
1. Go to **Settings → Pages**
86+
2. Set source to **GitHub Actions** (or deploy from `gh-pages` branch)
87+
3. Configure custom domain if needed
88+
4. Enable branch protection on main branch
89+
90+
### Step 8: Verify Deployment
91+
Check GitHub Actions workflow status in Actions tab, verify site loads at configured URL, and confirm all navigation works.
92+
93+
## Troubleshooting
94+
95+
For common issues and solutions, see `references/troubleshooting.md`, which covers:
96+
- Build failures and type errors
97+
- 404 errors after deployment
98+
- Broken links and GitHub Actions issues
99+
- Performance problems and content quality
100+
101+
## Bundled Resources
102+
103+
- `references/deploy-workflow.yml` - GitHub Actions workflow template
104+
- `references/configuration-guide.md` - Detailed Docusaurus configuration
105+
- `references/local-validation-guide.md` - Build and validation procedures
106+
- `references/github-actions-guide.md` - CI/CD setup and configuration
107+
- `references/troubleshooting.md` - Common issues and solutions
108+
- `references/performance-standards.md` - Performance targets and best practices
109+
110+
## Performance Targets
111+
112+
- **Build time**: < 30 seconds (typical)
113+
- **Page load**: < 3 seconds
114+
- **Bundle size**: Optimized for documentation
115+
- **Accessibility**: WCAG 2.1 AA compliance
116+
117+
## Quality Gates (Constitution v3.1.2)
118+
119+
Before deployment to production, verify:
120+
- [ ] All content passes validation-auditor validation
121+
- [ ] Local build completes without errors
122+
- [ ] No broken links or missing resources
123+
- [ ] TypeScript type checking passes
124+
- [ ] Performance targets met
125+
- [ ] Accessibility standards verified
126+
- [ ] GitHub Actions workflow configured correctly
127+
128+
**Reference**: See `.specify/memory/constitution.md` deployment standards section for complete production deployment standards.
129+
130+
## Tools Used
131+
132+
- Node.js/npm (v20+)
133+
- Docusaurus CLI
134+
- TypeScript
135+
- GitHub Actions
136+
- GitHub Pages

‎.claude/skills/docusaurus-deployer/references/configuration-guide.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Docusaurus GitHub Pages Configuration Guide
2+
3+
## Overview
4+
5+
Configure Docusaurus for GitHub Pages deployment by updating `docusaurus.config.ts` with the appropriate settings for the deployment target.
6+
7+
## Configuration Template
8+
9+
Update the Docusaurus config file (`docusaurus.config.ts`) with GitHub Pages-specific settings:
10+
11+
```typescript
12+
const config: Config = {
13+
title: 'Your Documentation Title',
14+
tagline: 'Documentation description',
15+
favicon: 'img/favicon.ico',
16+
17+
// GitHub Pages configuration
18+
url: 'https://username.github.io', // or 'https://username.github.io/repo-name' for project repos
19+
baseUrl: '/', // or '/<repository-name>/' for project repos
20+
organizationName: 'your-github-org-or-username',
21+
projectName: 'your-repository-name',
22+
deploymentBranch: 'gh-pages', // The branch GitHub Pages will serve from
23+
trailingSlash: false,
24+
25+
// ... rest of configuration
26+
};
27+
```
28+
29+
## Configuration Guidelines by Deployment Type
30+
31+
### User/Organization Pages
32+
33+
For repositories named `username.github.io` or `orgname.github.io`:
34+
35+
```typescript
36+
const config: Config = {
37+
url: 'https://username.github.io',
38+
baseUrl: '/',
39+
organizationName: 'username',
40+
projectName: 'username.github.io',
41+
deploymentBranch: 'main', // or 'master'
42+
// ... rest of config
43+
};
44+
```
45+
46+
**Key Points:**
47+
- `baseUrl` is `/` (at root)
48+
- `projectName` matches the repository name exactly
49+
- Can deploy from `main`, `master`, or `gh-pages` branch
50+
51+
### Project Pages
52+
53+
For repositories with separate names (e.g., `my-docs`, `documentation`, `agentic-ai`):
54+
55+
```typescript
56+
const config: Config = {
57+
url: 'https://username.github.io/repo-name',
58+
baseUrl: '/repo-name/',
59+
organizationName: 'username',
60+
projectName: 'repo-name',
61+
deploymentBranch: 'gh-pages',
62+
// ... rest of config
63+
};
64+
```
65+
66+
**Key Points:**
67+
- `baseUrl` includes the repository name with trailing slash: `/repo-name/`
68+
- `projectName` matches the repository name exactly
69+
- Always use `gh-pages` as deployment branch for project repositories
70+
71+
## Project Analysis Checklist
72+
73+
Before updating configuration, verify:
74+
75+
- **Docusaurus configuration file exists**: `docusaurus.config.ts` or `docusaurus.config.js`
76+
- **Sidebar configuration is present**: `sidebars.js` or `sidebars.ts`
77+
- **Package.json specifies correct Node.js version**: Check `engines.node` field (typically v20+)
78+
- **All required dependencies are listed**: Including `@docusaurus/core`, `@docusaurus/preset-classic`, etc.
79+
80+
## Configuration Best Practices
81+
82+
### URL Configuration
83+
- **User/Organization Pages**: `url` = `https://username.github.io`, `baseUrl` = `/`, `projectName` = `username.github.io`
84+
- **Project Pages**: `url` = `https://username.github.io/repo-name`, `baseUrl` = `/repo-name/`, `projectName` = `repo-name`
85+
86+
### Deployment Settings
87+
- Always use `gh-pages` as the deployment branch for project repositories
88+
- For user/organization pages, can use `main` or `master` branch
89+
- Ensure TypeScript configuration includes `typescript` in devDependencies
90+
91+
### File Organization
92+
- Ensure Docusaurus config is at the root of the docs subdirectory (e.g., `website/docusaurus.config.ts`)
93+
- Verify `sidebars.ts` exists and properly references all documentation files
94+
- Check that documentation files follow naming conventions (kebab-case for files)
95+
96+
## Common Configuration Issues
97+
98+
### Incorrect baseUrl
99+
100+
**Problem**: Site deploys but shows 404 or broken links
101+
102+
**Solution**: Verify baseUrl matches deployment target:
103+
- For `https://username.github.io/repo-name`: baseUrl should be `/repo-name/`
104+
- For `https://username.github.io`: baseUrl should be `/`
105+
106+
### Type Errors in docusaurus.config.ts
107+
108+
**Problem**: TypeScript errors prevent build
109+
110+
**Solution**:
111+
1. Verify all imported types are properly declared
112+
2. Check Config type definition: `import type { Config } from "@docusaurus/types"`
113+
3. Ensure all config properties match the current Docusaurus version
114+
4. Run `npm run typecheck` to identify specific errors
115+
116+
### Plugin Incompatibilities
117+
118+
**Problem**: Plugin conflicts or version mismatches
119+
120+
**Solution**:
121+
1. Verify plugin versions match installed Docusaurus version
122+
2. Check plugin documentation for configuration requirements
123+
3. Review error messages for plugin-specific issues
124+
4. Update plugins to compatible versions if needed
125+
126+
## Customization Examples
127+
128+
### Adding Custom Domain
129+
130+
To use a custom domain instead of `username.github.io/repo-name`:
131+
132+
1. Update config:
133+
```typescript
134+
const config: Config = {
135+
url: 'https://your-custom-domain.com',
136+
baseUrl: '/',
137+
// ... rest of config
138+
};
139+
```
140+
141+
2. Add CNAME file in static directory: `static/CNAME`
142+
3. Configure custom domain in GitHub repository settings
143+
144+
### Modifying Preset Options
145+
146+
Customize the classic preset in `docusaurus.config.ts`:
147+
148+
```typescript
149+
presets: [
150+
[
151+
'classic',
152+
{
153+
docs: {
154+
sidebarPath: './sidebars.ts',
155+
editUrl: 'https://github.com/username/repo/tree/main/docs/',
156+
},
157+
blog: {
158+
showReadingTime: true,
159+
},
160+
theme: {
161+
customCss: './src/css/custom.css',
162+
},
163+
} satisfies Preset.Options,
164+
],
165+
],
166+
```
167+
168+
## Verification Checklist
169+
170+
After updating configuration:
171+
172+
- [ ] `docusaurus.config.ts` is valid TypeScript (no type errors)
173+
- [ ] `url` and `baseUrl` match your GitHub Pages deployment target
174+
- [ ] `organizationName` and `projectName` are correct
175+
- [ ] `deploymentBranch` is set to appropriate branch ('gh-pages' for projects, 'main'/'master' for user pages)
176+
- [ ] `trailingSlash` is set to false for consistency
177+
- [ ] `npm run typecheck` passes with no errors
178+
- [ ] `npm run build` completes successfully

‎.claude/skills/docusaurus-deployer/references/deploy-workflow.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout repository
22+
uses: actions/checkout@v4
23+
24+
- name: Setup Node.js with TypeScript support
25+
uses: actions/setup-node@v4
26+
with:
27+
node-version: '20'
28+
cache: 'npm'
29+
cache-dependency-path: './book-source/package-lock.json'
30+
31+
- name: Install dependencies
32+
working-directory: ./book-source
33+
run: npm ci
34+
35+
- name: Run TypeScript type check
36+
working-directory: ./book-source
37+
run: npm run typecheck
38+
39+
- name: Build website
40+
working-directory: ./book-source
41+
run: npm run build
42+
43+
- name: Upload artifact
44+
uses: actions/upload-pages-artifact@v2
45+
with:
46+
path: './book-source/build'
47+
48+
deploy:
49+
environment:
50+
name: github-pages
51+
url: ${{ steps.deployment.outputs.page_url }}
52+
runs-on: ubuntu-latest
53+
needs: build
54+
steps:
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@v2

0 commit comments

Comments
 (0)