Docusaurus GitHub Pages Deployer

Automate building and deploying Docusaurus documentation sites to GitHub Pages with local validation before CI/CD triggering.

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.

What This Skill Does

1. Project Analysis - Examine Docusaurus structure and dependencies
2. Local Configuration Validation - Verify Docusaurus config and sidebars
3. Local Build & Testing - Build site locally and validate output
4. Content Verification - Check for broken links and syntax errors
5. GitHub Pages Setup - Configure repository and deployment settings
6. CI/CD Automation - Set up GitHub Actions workflows
7. Deployment Verification - Validate successful deployment

When to Use This Skill

Deploy Docusaurus to GitHub Pages when:

• Setting up documentation deployment for the first time
• Making updates to documentation before publishing
• Updating deployment configuration
• Troubleshooting deployment issues
• Managing multiple documentation sites
• Ensuring documentation quality before production

How to Use This Skill

Follow the validate-locally-then-publish workflow:

Step 1: Prepare Repository Configuration

Gather GitHub organization/username, repository name, deployment target (user/project pages), and custom domain (optional).

Step 2: Analyze Project Structure

Examine Docusaurus project:

ls -la path_to_docusaurus_project/
cat path_to_docusaurus_project/docusaurus.config.ts
cat path_to_docusaurus_project/sidebars.ts

Verify docusaurus.config.ts, sidebars.js/ts, package.json engines field, and dependencies exist.

For detailed configuration guidance, see

references/configuration-guide.md

.

Step 3: Update Docusaurus Configuration

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).

Step 4: Build and Validate Locally

Install dependencies, run type checking, build site, validate output, test locally, and verify content quality.

Execute:

npm ci
npm run typecheck
npm run build
npm run serve

For detailed validation procedures, see

references/local-validation-guide.md

.

Step 5: Commit and Push to Main

After successful local validation:

git add .
git commit -m "Update documentation: [description]"
git push origin main

This triggers the GitHub Actions workflow.

Step 6: Set Up GitHub Actions

Create

.github/workflows/deploy.yml

using the template in

references/deploy-workflow.yml

.

For detailed workflow configuration and troubleshooting, see

references/github-actions-guide.md

.

Step 7: Configure GitHub Pages in Repository Settings

1. Go to Settings → Pages
2. Set source to GitHub Actions (or deploy from

   gh-pages

   branch)
3. Configure custom domain if needed
4. Enable branch protection on main branch

Step 8: Verify Deployment

Check GitHub Actions workflow status in Actions tab, verify site loads at configured URL, and confirm all navigation works.

Troubleshooting

For common issues and solutions, see

references/troubleshooting.md

, which covers:

• Build failures and type errors
• 404 errors after deployment
• Broken links and GitHub Actions issues
• Performance problems and content quality

Bundled Resources

• references/deploy-workflow.yml

  - GitHub Actions workflow template

• references/configuration-guide.md

  - Detailed Docusaurus configuration

• references/local-validation-guide.md

  - Build and validation procedures

• references/github-actions-guide.md

  - CI/CD setup and configuration

• references/troubleshooting.md

  - Common issues and solutions

• references/performance-standards.md

  - Performance targets and best practices

• references/remark-plugin-patterns.md

  - Remark plugin development (AST transforms, directive syntax, nested containers)

Performance Targets

• Build time: < 30 seconds (typical)
• Page load: < 3 seconds
• Bundle size: Optimized for documentation
• Accessibility: WCAG 2.1 AA compliance

Quality Gates (Constitution v3.1.2)

Before deployment to production, verify:

• All content passes validation-auditor validation
• Local build completes without errors
• No broken links or missing resources
• TypeScript type checking passes
• Performance targets met
• Accessibility standards verified
• GitHub Actions workflow configured correctly

Reference: See

.specify/memory/constitution.md

deployment standards section for complete production deployment standards.

Tools Used

• Node.js/npm (v20+)
• Docusaurus CLI
• TypeScript
• GitHub Actions
• GitHub Pages