Docusaurus Setup

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:

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