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.
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.
Deploy Docusaurus to GitHub Pages when:
Follow the validate-locally-then-publish workflow:
Gather GitHub organization/username, repository name, deployment target (user/project pages), and custom domain (optional).
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.
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).
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.
After successful local validation:
git add .
git commit -m "Update documentation: [description]"
git push origin main
This triggers the GitHub Actions workflow.
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.
gh-pages branch)Check GitHub Actions workflow status in Actions tab, verify site loads at configured URL, and confirm all navigation works.
For common issues and solutions, see references/troubleshooting.md, which covers:
references/deploy-workflow.yml - GitHub Actions workflow templatereferences/configuration-guide.md - Detailed Docusaurus configurationreferences/local-validation-guide.md - Build and validation proceduresreferences/github-actions-guide.md - CI/CD setup and configurationreferences/troubleshooting.md - Common issues and solutionsreferences/performance-standards.md - Performance targets and best practicesBefore deployment to production, verify:
Reference: See .specify/memory/constitution.md deployment standards section for complete production deployment standards.