Skip to main content

GitHub Copilot Instructions for Documentation Site (docsite) Folder

Overview​

This folder contains a Docusaurus-based documentation site for the Reports application. The site is built with Docusaurus 3.8.1 and deployed to Cloudflare Pages.

Technology Stack​

  • Docusaurus: 3.8.1
  • Node.js: 22.x (specified in package.json engines)
  • React: 19.0.0
  • TypeScript: ~5.6.2
  • Search: docusaurus-lunr-search
  • Deployment: Cloudflare Pages via Wrangler

Setup Instructions​

Prerequisites​

  1. Install Node.js 22.x:
# Using nvm (recommended)
nvm install 22
nvm use 22

# Or download from https://nodejs.org/
  1. The project uses npm (not yarn) for dependency management

Development Setup​

cd docsite

# Install dependencies
npm ci

# Start development server
npm start

# The site will be available at http://localhost:3000

Building​

cd docsite

# Build the static site
npm run build

# The output will be in the `build` directory

# Serve the built site locally
npm run serve

File Structure​

  • docs/ - Markdown documentation files
  • src/ - Custom React components and pages
  • static/ - Static assets (images, files)
  • docusaurus.config.ts - Main Docusaurus configuration
  • sidebars.ts - Sidebar configuration
  • package.json - Dependencies and scripts
  • tsconfig.json - TypeScript configuration
  • wrangler.jsonc - Cloudflare Pages deployment configuration

Important Notes​

Docusaurus does not support symlinks in the docs folder. If you need to include content from other parts of the repository:

  1. Copy the file instead of symlinking
  2. Use the CI/CD pipeline to copy files during build (see .github/workflows/docsite.yml)
  3. Use a pre-build script to copy files if needed

PostCSS Conflict​

The parent directory contains a postcss.config.js file that conflicts with Docusaurus's PostCSS configuration. The CI workflow removes this file before building:

- name: Remove postcss.config.js
  run: rm -f ../postcss.config.js

This is necessary for the build to succeed.

Development Workflow​

Adding Documentation​

  1. Create a new .md file in the docs/ directory
  2. Add frontmatter if needed:
---
sidebar_position: 1
---

# Your Title Here
  1. The sidebar is auto-generated from the file structure (see sidebars.ts)
  2. Test locally with npm start

Including External Content​

Since symlinks don't work, use a build-time copy:

  1. Add a step to .github/workflows/docsite.yml before the build:
- name: Copy external documentation
  run: |
    cp ../.github/instructions/terraform.instructions.md docs/infra-setup.md
  1. Ensure the copied file has proper frontmatter for Docusaurus
  2. Add the file to .gitignore if it's only generated during build

Styling and Components​

  • Custom CSS: Add to src/css/custom.css
  • Custom React components: Add to src/components/
  • Custom pages: Add to src/pages/

Search Configuration​

The site uses docusaurus-lunr-search for client-side search. It automatically indexes all documentation pages.

CI/CD Integration​

GitHub Actions Workflow​

The .github/workflows/docsite.yml workflow:

  1. Checks out the code
  2. Sets up Node.js 22.x (using node-version-file from package.json)
  3. Removes the parent postcss.config.js file
  4. Installs dependencies with npm ci
  5. Builds the site with npm run build
  6. Deploys to Cloudflare Pages

Deployment​

The site is automatically deployed to Cloudflare Pages on:

  • Push to main branch (when docsite files change)
  • Pull requests (when docsite files change)

Deployment requires:

  • CLOUDFLARE_ACCOUNT_TOKEN secret
  • CLOUDFLARE_ACCOUNT_ID secret

Common Tasks​

Updating Dependencies​

cd docsite

# Update all dependencies
npm update

# Update specific package
npm update @docusaurus/core

# Check for outdated packages
npm outdated

Clearing Cache​

cd docsite

# Clear Docusaurus cache
npm run clear

Type Checking​

cd docsite

# Run TypeScript type checker
npm run typecheck

Adding a New Plugin​

  1. Install the plugin:
npm install --save docusaurus-plugin-name
  1. Add to docusaurus.config.ts:
plugins: [
  'docusaurus-plugin-name',
],

Troubleshooting​

Build Fails with PostCSS Error​

Solution: Ensure the parent postcss.config.js is removed before building (done automatically in CI)

Solution: Replace symlinks with actual files or copy during build

Node Version Mismatch​

Solution: Use Node 22.x as specified in package.json engines field

Module Not Found Errors​

Solution:

rm -rf node_modules package-lock.json
npm install

TypeScript Errors​

Solution: Check tsconfig.json and ensure all necessary type definitions are installed

Best Practices​

  1. Always test locally before committing documentation changes
  2. Use descriptive file names for documentation files
  3. Add frontmatter to control sidebar position and labels
  4. Optimize images before adding to static/ folder
  5. Keep dependencies updated but test thoroughly
  6. Use semantic versioning for the docsite package.json
  7. Write clear, concise documentation with examples
  8. Use code blocks with language syntax highlighting
  9. Link to related documentation for better navigation
  10. Test builds in CI before merging

Resources​

When Working with Documentation​

  1. Test First: Always run npm start to preview changes
  2. Check Links: Ensure all internal links work correctly
  3. Format Code: Use proper syntax highlighting in code blocks
  4. Structure Content: Use headings, lists, and sections appropriately
  5. Include Examples: Provide code examples where helpful
  6. Keep It Updated: Update documentation when code changes
  7. Follow Style: Match the existing documentation style
  8. Build Locally: Run npm run build before committing to catch errors