Docusaurus Setup Skill

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 the Docusaurus site on github pages.
• •perform git add ., git commit -m "update site - [detail]" and git push -u origin main operation
• •You’re configuring if not already set docusaurus.config.js (title, baseUrl, theme plugins, navbar, footer).
• •You’re editing sidebars.js to match your course or project structure.
• •You need to set up deployment of a Docusaurus site to GitHub Pages with CI/CD.

How This Skill Works

1. •

   Confirm build output:

   • •Run npm run build locally to ensure the site compiles without errors and outputs to build/.
   • •Fix any configuration issues (e.g., broken links or missing assets) before proceeding.
2. •

   Configure docusaurus.config.js if not already set:

   • •Minimal Configuration Tip: Focus on url, baseUrl, organizationName, projectName, and deploymentBranch for initial setup.
   • •Open docusaurus.config.ts and check these fields:
     • •url: Should be https://<github-username>.github.io.
     • •baseUrl: Should be "/<repo-name>/" if the project is not served from root.
     • •organizationName and projectName: Match your GitHub account and repository.
     • •deploymentBranch: Usually gh-pages.
     • •Optional fields like trailingSlash, i18n settings and favicon should reflect the project’s needs.
   • •Customize the navbar and footer links to mirror the course modules and external resources.
   • •Add or remove plugins (e.g., search, analytics) as needed for your use case.
   • •Security Note: Avoid hardcoding sensitive information directly. Use environment variables (e.g., .env files or GitHub Secrets) for tokens or other confidential data.
3. •

   Edit sidebars.js:

   • •Minimal Configuration Tip: Define a basic structure with your main content categories.
   • •Define the sidebar structure to reflect the course outline or document hierarchy.
   • •Group chapters and sections logically, using categories for modules and weeks.
   • •Ensure that sidebars update automatically when new Markdown/MDX files are added.
4. •

   Theme customization:

   • •Adjust styling via @theme components or CSS for consistent colors and typography.
   • •Override theme components in the src/theme directory (e.g., custom layout or code block styles).
   • •Test changes locally using npm run start to ensure responsiveness.
5. •

   Prepare for GitHub Pages deployment:

   • •Initialize a Git repository and connect it to GitHub using the GitHub CLI (e.g., gh repo create <repo> --public).
   • •Push the initial site to the repository.
   • •In docusaurus.config.js, set the organizationName, projectName, and deploymentBranch fields to match your GitHub org/user and repository.
   • •Important: If GitHub Pages is not yet enabled for your repository, run gh pages enable --branch gh-pages via the GitHub CLI.
6. •

   Set up CI/CD pipeline:

   • •Check if .github/workflows/deploy.yml exists in the repository.
   • •If it doesn’t exist or needs updating, create it with a workflow similar to:
   yaml

     name: Deploy Docusaurus to GitHub Pages
     on:
       push:
         branches:
           - main
     jobs:
       build:
         runs-on: ubuntu-latest
         steps:
         - uses: actions/checkout@v3
         - uses: actions/setup-node@v3
           with:
             node-version: '18'
         - run: npm ci
         - run: npm run build
         - uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./build
             publish_branch: gh-pages
   

   1. •Checks out the repository.
   2. •Installs Node dependencies (e.g., using actions/setup-node).
   3. •Builds the static site (npm run build).
   4. •Deploys the contents of build to the gh-pages branch using actions-gh-pages or gh CLI.
   • •Commit and push the workflow to the default branch; GitHub Actions will handle future deployments on push.
7. •

   Deployment Verification (New Content/Updates):

   • •Run npm run start locally to verify site appearance.
   • •Commit your changes:
     • •git add .
     • •git commit -m "Update site - [detail of changes]"
     • •git push origin main (or your default branch)
   • •After the GitHub Actions workflow finishes, the site will be available at https://<username>.github.io/<repo>/.
   • •Make adjustments to configuration files if deployment fails (e.g., baseUrl mismatch).
   • •Once completed, visit https://<github-username>.github.io/<repo-name>/ to confirm your updated book is live.
8. •

   Ongoing usage:

   • •Each time new content is committed, the workflow automatically redeploys the site.

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

Output Format

When using this skill, provide:

• •A clear repository name and the desired site name.
• •Any custom sections or modules to include in sidebars.js.
• •Details about theme changes (e.g., custom color palette, fonts).
• •Confirmation that the GitHub CLI is authenticated on your machine.

The skill will return:

1. •Project Setup Summary: Path to the new Docusaurus project and commands executed.
2. •Configuration Details: A checklist of changes made to docusaurus.config.js and sidebars.js.
3. •Confirmation Deploy.yml: Confirmation of whether .github/workflows/deploy.yml already existed or was created.
4. •CI/CD Instructions: A ready-to-commit deploy.yml workflow for GitHub Actions and notes on enabling GitHub Pages.
5. •Next Steps:

• •First find the Docusaurus project folder cd <project_folder_name>
• •How to add content to the docs or blog folders inside Docusaurus project and verify deployment.

Example

Input: “I just added a new chapter and want to publish the updated Docusaurus site.”

Output:

• •Config Check: Verified url is https://jane-doe.github.io, baseUrl is /physical-ai-book/, and deploymentBranch is gh-pages. No changes needed.
• •Configuration Details: Updated site title to “Robotics Course Book,” , added modules to sidebars.js (Module 1: ROS 2, Module 2: Digital Twin…).
• •Workflow Creation: Added .github/workflows/deploy.yml for automatic deployment on pushes to main.
• •Next Steps: Add your markdown chapters to docs/,Run npm run build locally if desired, commit all changes (git add . and git commit -m "Add Chapter 3 and deployment pipeline"), and push (git push origin main). After the GitHub Actions workflow finishes, the site will be available at https://<github-username>.github.io/physical-ai-book/.