docusaurus-deployer
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.
When & Why to Use This Skill
The docusaurus-deployer skill is a comprehensive automation tool designed to streamline the deployment of Docusaurus documentation sites to GitHub Pages. It simplifies the entire lifecycle from local configuration and build validation to setting up GitHub Actions for continuous integration and delivery (CI/CD). By automating repository settings, environment configurations, and local testing, it ensures a reliable, error-free publishing process for developers and technical writers, significantly reducing the manual overhead of managing static site deployments.
Use Cases
- 1. Initial Documentation Launch: Automate the first-time setup and deployment of a Docusaurus site to GitHub Pages, including repository configuration and environment setup.
- 2. Pre-Production Quality Assurance: Perform local builds, type checking, and link verification to ensure documentation quality and prevent broken builds before triggering live CI/CD workflows.
- 3. CI/CD Pipeline Automation: Generate and configure standardized GitHub Actions workflows to enable seamless, automated updates to documentation upon every code push to the main branch.
- 4. Deployment Troubleshooting: Use integrated diagnostic steps to identify and resolve common hosting issues such as 404 errors, build failures, or incorrect repository settings.
| name | docusaurus-deployer |
|---|---|
| version | 1.0 |
| 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. |
Docusaurus GitHub Pages Deployer
Automate building and deploying Docusaurus documentation sites to GitHub Pages with local validation before CI/CD triggering.
What This Skill Does
- Project Analysis - Examine Docusaurus structure and dependencies
- Local Configuration Validation - Verify Docusaurus config and sidebars
- Local Build & Testing - Build site locally and validate output
- Content Verification - Check for broken links and syntax errors
- GitHub Pages Setup - Configure repository and deployment settings
- CI/CD Automation - Set up GitHub Actions workflows
- 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
- Go to Settings → Pages
- Set source to GitHub Actions (or deploy from
gh-pagesbranch) - Configure custom domain if needed
- 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 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 practices
Performance Targets
- Build time: < 30 seconds (typical)
- Page load: < 3 seconds
- Bundle size: Optimized for documentation
- Accessibility: WCAG 2.1 AA compliance
Tools Used
- Node.js/npm (v20+)
- Docusaurus CLI
- TypeScript
- GitHub Actions
- GitHub Pages