Skip to main content

Docusaurus

📦Website
💰

Costs

Monthly:Free
Annual:Free
🔑

Access

INTERNAL
ℹ️

Documentation site for Pacing Agency tech stack

Purpose: Documentation site for Pacing Agency tech stack. Provides a browsable, searchable interface for all tool documentation, architecture notes, and operational guides.

Last verified: December 2025

Build test: Verified auto-sync working (December 2025) - tools sync automatically on push to GitHub via prebuild hook.

Account Details​

Overview​

Docusaurus is a static site generator that transforms our Markdown documentation into a searchable, navigable website. The site automatically syncs all tools/*.md files on every build, making it easy to keep documentation up to date.

Key Features:

  • Automatic sync of all tools/*.md files into browsable docs
  • Search functionality across all documentation
  • Custom Pacing-branded theme matching pacing.agency visual style
  • Automatic deployment to Cloudflare Pages on Git push
  • MDX safety checks (escapes email addresses, handles file links, detects potential secrets)
  • Protected access via Cloudflare Access with Google OAuth authentication

Build Process​

The Docusaurus site is built automatically on every push to the main branch via Cloudflare Pages:

  1. Pre-build step: scripts/sync-tools.cjs runs automatically (via prebuild hook in package.json)

    • Reads all tools/*.md files (except README.md)
    • Strips existing frontmatter and extracts H1 headings as titles
    • Fixes MDX issues (escapes emails, converts file:// links)
    • Checks for potential API keys/secrets (logs warnings)
    • Writes transformed files to docs/tools/<tool-name>.md

  2. Build step: Docusaurus compiles the site

    • Processes all Markdown/MDX files
    • Generates static HTML/CSS/JS
    • Outputs to build/ directory

  3. Deploy step: Cloudflare Pages serves the build/ directory

Local build:

cd docusaurus
npm install
npm run build  # Runs sync + build
npm start      # Runs sync + dev server

Sync Script Behavior​

The docusaurus/scripts/sync-tools.cjs script:

  • Source of truth: tools/*.md files in the parent directory
  • Output: docusaurus/docs/tools/*.md (generated, do not edit directly)
  • Transformations:
    • Removes existing frontmatter blocks
    • Extracts first H1 heading as page title
    • Removes the H1 from body (Docusaurus uses frontmatter title)
    • Escapes email addresses: <email@domain> → &lt;email@domain&gt;
    • Converts file:// links to inline code blocks
    • Adds Docusaurus frontmatter with id, title, and source fields
  • Safety checks: Warns if JWT-like tokens are detected (doesn't fail build)
  • Exclusions: Skips tools/README.md

Important: Always edit source files in tools/, never edit generated files in docusaurus/docs/tools/ (they get overwritten on every build).

Adding Custom Pages​

Option 1: Add a tool doc (auto-synced)​

  1. Create tools/<tool-name>.md in the parent directory
  2. The sync script automatically picks it up on the next build
  3. It appears in the sidebar under "Tools"

Option 2: Create a custom Docusaurus page​

  1. Create a new file in docusaurus/docs/ (not docs/tools/)
  2. Add proper frontmatter: 
    ---
    id: my-page
    title: My Page Title
    ---

    Your content here...
  3. Update docusaurus/sidebars.ts to include it in navigation if needed

Option 3: Edit core pages​

  • docusaurus/docs/intro.md - Based on README.md (manual sync)
  • docusaurus/docs/architecture.md - Based on architecture.md (manual sync)
  • docusaurus/docs/tools.md - Tools overview page (edit directly)

Configuration​

  • Config file: docusaurus/docusaurus.config.ts
  • Sidebar: docusaurus/sidebars.ts
  • Theme: Custom CSS in docusaurus/src/css/custom.css (matches pacing.agency brand)
  • Homepage: docusaurus/src/pages/index.tsx

Dependencies​

  • Node.js >= 20.0
  • npm (comes with Node.js)
  • Dependencies managed in docusaurus/package.json

MDX Validation​

The build process includes two layers of MDX validation to catch syntax errors before deployment:

Validation Process​

The docusaurus/scripts/validate-mdx.cjs script runs automatically as part of the prebuild hook and performs two validation steps:

  1. Custom Pattern Checks (Step 1):

    • Scans all .md and .mdx files in docs/
    • Checks for common MDX syntax issues:
      • Unescaped less-than symbols with numbers (e.g., <5% should be {'<5%'} or &lt;5%)
      • Unescaped email addresses (e.g., <email@domain> should be &lt;email@domain&gt;)
      • Unescaped special characters after <
      • Unescaped curly braces in text (for .md files)
      • Potential unclosed JSX tags
    • Provides specific error messages with file, line, and column numbers
    • Groups errors by type for easier fixing

  2. docusaurus-mdx-checker (Step 2):

    • Runs npx docusaurus-mdx-checker to validate MDX v3 compatibility
    • Uses the same MDX parser as Docusaurus v3
    • Catches parsing errors that would cause build failures
    • Reports which files are incompatible with MDX v3

Running Validation Manually​

To run validation manually:

cd docusaurus
node ./scripts/validate-mdx.cjs

This will:

  • Run both validation steps
  • Report any issues found
  • Exit with code 1 if issues are found (blocking build)
  • Exit with code 0 if all checks pass

Validation Output​

On success:

[validate-mdx] Starting MDX validation...
[validate-mdx] Step 1: Running custom pattern checks...
[validate-mdx] ✓ Custom pattern checks passed.
[validate-mdx] Step 2: Running docusaurus-mdx-checker...
[validate-mdx] ✓ docusaurus-mdx-checker passed.
[validate-mdx] ✓ All MDX validation checks passed.

On failure, the script will:

  • Show detailed error messages grouped by type
  • Include file paths, line numbers, and column numbers
  • Provide specific fix suggestions
  • Exit with code 1 to block the build

Integration​

  • Pre-build hook: Validation runs automatically via npm run prebuild (called before npm run build)
  • CI/CD: Cloudflare Pages runs validation as part of the build process
  • Local development: Run npm run build or npm start to trigger validation
  • Custom validator: docusaurus/scripts/validate-mdx.cjs - Pattern-based checks for common issues
  • docusaurus-mdx-checker: https://github.com/slorber/docusaurus-mdx-checker - Official Docusaurus MDX v3 compatibility checker
  • Sync script: docusaurus/scripts/sync-tools.cjs - Also performs some MDX fixes (email escaping, file link conversion)

Troubleshooting​

Build fails with MDX errors​

  • Run node ./scripts/validate-mdx.cjs manually to see detailed error messages
  • Check sync script warnings for potential issues
  • Look for unescaped email addresses (<email@domain> should be &lt;email@domain&gt;)
  • Check for file:// links that need to be converted
  • Review docusaurus-mdx-checker output for MDX v3 compatibility issues
  • Common fixes:
    • Escape less-than symbols: <5% → {'<5%'} or &lt;5%
    • Escape email addresses: <email@domain> → &lt;email@domain&gt;
    • Escape curly braces in .md files: { → {'{'} (not needed in .mdx files)

Tools not appearing in sidebar​

  • Ensure the file is in tools/ (not docusaurus/docs/tools/)
  • Check that the filename matches *.md (not README.md)
  • Run npm run prebuild manually in docusaurus/ to see sync output

Cloudflare Pages deploy command error (wrangler deploy)​

  • Symptom: Cloudflare build succeeds but deploy fails with Missing entry-point to Worker script or to assets directory and logs show Executing user deploy command: npx wrangler deploy.
  • Cause: Pages is for static hosting; wrangler deploy expects a Worker entry point or explicit assets.directory, which we do not configure for this project.
  • Fix (recommended): In the Cloudflare Pages project:
    • Keep Root directory = docusaurus, Build command = npm run build, Output directory = build.
    • Set the Deploy command to a simple no-op that always succeeds, for example:
      • echo "Cloudflare Pages will deploy the docusaurus/build output"
    • (Optional) Use the same echo command for the non‑production branch deploy command.
    • Do not use npx wrangler deploy for this static Docusaurus site.

Changes not showing up locally​

  • For tools: restart dev server or run npm run prebuild
  • For custom pages: changes should hot-reload automatically

Cloudflare Pages Setup​

The site is deployed via Cloudflare Pages with automatic builds on every push to main.

Current project: techstackdocs1 (connected to Pacing-Agency/techstackdocs)

Initial Setup​

  1. Create Pages project (via Dashboard):

    • Go to Cloudflare Dashboard → Workers & Pages → Create application → Pages
    • Select "Import an existing Git repository"
    • Or create manually and connect Git later

  2. Connect GitHub repository (via Dashboard):

    • Go to Cloudflare Dashboard → Workers & Pages → [project-name]
    • Click "Connect to Git" or "Change source"
    • Select GitHub and authorize
    • Choose repository: Pacing-Agency/techstackdocs
    • Confirm branch: main

  3. Configure build settings (via Dashboard):

    • Framework preset: Docusaurus (auto-fills settings below)
    • Production branch: main
    • Build command: npm run build
    • Build directory: build
    • Root directory: docusaurus

  4. Add custom domain (via Dashboard):

    • Go to Settings → Custom domains
    • Add: docs.pacing.agency
    • DNS will be configured automatically

  5. Configure Cloudflare Access (if needed):

    • Go to Zero Trust → Access → Applications
    • Update application to point to the Pages project
    • See Cloudflare Access for details

Verified Configuration (December 2025)​

Project: techstackdocs1

  • GitHub: Pacing-Agency/techstackdocs
  • Branch: main
  • Build command: npm run build
  • Root directory: docusaurus
  • Output directory: build
  • Custom domain: docs.pacing.agency (configured via Dashboard)

Build Configuration​

SettingValue
Framework presetDocusaurus
Production branchmain
Build commandnpm run build
Build directorybuild
Root directorydocusaurus

The build process automatically:

  • Runs npm run prebuild (syncs tools/*.md files)
  • Runs npm run build (builds Docusaurus site)
  • Deploys the build/ directory

Migrating to New Repository​

If the GitHub repository is moved or renamed:

  1. Create new Pages project (or update existing):

    wrangler pages project create <project-name> --production-branch=main

  2. Connect new repository via Dashboard (GitHub OAuth required)

  3. Update build settings to match configuration above

  4. Add custom domain if needed

  5. Update Cloudflare Access application to point to new project

  6. Delete old project once verified (remove custom domain first)