Docusaurus at Pacing Agency

Docusaurus powers our internal tech stack documentation site at docs.pacing.agency. It transforms our Markdown documentation into a searchable, navigable website with automatic deployment to Cloudflare Pages.

What is Docusaurus?

Docusaurus is a static site generator built by Meta (Facebook) that is specifically designed for documentation websites. It takes Markdown files and converts them into a modern, fast-loading documentation site with:

• Automatic navigation - Sidebars generated from your file structure
• Search functionality - Search across all documentation with Algolia integration
• Versioning support - Maintain multiple versions of docs
• MDX support - Use React components in Markdown
• Customisable themes - Brand your documentation site
• SEO optimised - Static HTML for fast loading and good SEO

How We Use Docusaurus

Primary Use Case

Our Docusaurus site serves as the single source of truth for Pacing Agency's tech stack documentation. It provides:

1. Tool Documentation - Every tool in our stack has a dedicated page with costs, renewal dates, IDs, owners, integration points, and automation workflows, organised by category with visual metadata components
2. Cost Tracking - Aggregated monthly and annual costs across categories, surfaced on the Tools overview
3. Architecture Documentation - High-level overview of our tech stack, data flows, and infrastructure
4. Operational Guides - Step-by-step guides for common tasks and best practices
5. Feature Documentation - Reusable components and features that can be added to new Docusaurus repos

Key Features We've Built

• Tool Categorization System - Tools organised by category (Website, Self-Hosting, Operational Tools, etc.) with cost tracking and renewal management
• ToolMetadata Component - Colour-coded metadata cards at the top of each tool page showing costs, access links, account types, and renewals
• CategorySummary Component - Visual summary cards on category pages with total tools, monthly costs, and annual costs
• ToolsOverview Component - Interactive expandable category cards on the main tools page with full cost overview
• Auto-sync Script (Tools) - Automatically syncs tools/*.md files to categorised Docusaurus structure on every build
• Auto-sync Script (Scripts) - Automatically syncs scripts/resources/*/README.md files to the Scripts section on every build; extra .md files in the same folder (with frontmatter title:) become sub-pages
• Sections Configuration - Centralised config file (docusaurus/config/sections.ts) for managing documentation sections, add a new section in one place
• CSV Integration - Tool metadata synced from TwentyCRM export (costs, categories, renewals, account types)
• Mermaid Diagrams - Visual diagramming for architecture, workflows, and data flows
• FAQ Structured Data - SEO-friendly FAQ component with toggleable structured data for internal vs external sites
• Copy/Download Button - Button on every doc page to copy content as plaintext/markdown or download as a markdown file
• MDX Validation - Pre-build validation to catch syntax errors before deployment
• Link Checker - Automated detection of broken internal and external links
• Documentation Verification - last_verified freshness checks and outdated documentation reporting
• Algolia Search - Two-index setup: keyword search (PacingDocs1Index) for fast results plus dedicated markdown index (PacingDocs1Index-markdown) for Ask AI full-page context
• Downloadable Script Zips - Every script folder has an auto-generated zip with credential scanning; download: frontmatter in source READMEs drives the download block on each page
• Custom Branding - Pacing Agency brand colours and styling

Deployment

The site is automatically deployed to Cloudflare Pages on every push to the main branch:

• Primary URL: https://docs.pacing.agency
• Cloudflare Pages: https://techstackdocs.pages.dev
• Authentication: Cloudflare Access with Google OAuth (internal only)

Benefits for Our Team

1. Centralised Knowledge - All tech stack information in one searchable location
2. Always Up-to-Date - Auto-sync ensures docs stay current with code changes
3. Easy to Maintain - Edit Markdown files, commit, and deploy automatically
4. Discoverable - Built-in search helps team members find information quickly
5. Reusable - Features and components can be copied to new documentation projects

Project Structure

Our Docusaurus setup follows a maintainable structure that separates:

• Source files (tools/*.md) - Edit these directly
• Generated files (docusaurus/docs/tools/*.md) - Auto-generated, never edit
• Generated script pages (docusaurus/docs/scripts/*.md) - Auto-generated from scripts/resources/*/README.md
• Custom pages (docusaurus/docs/*.md) - Standalone documentation pages
• Features (docusaurus/docs/docusaurus/features/) - Reusable components and setup guides

See Repository Structure for detailed information about how to add features and maintain the project.

Frequently Asked Questions

FAQs

Edit the source files in `tools/*.md` directly. These files are automatically synced to the Docusaurus site on every build. Never edit files in `docusaurus/docs/tools/*.md` as they are auto-generated and will be overwritten.

Each tool in our stack has a dedicated page in the Tools section. Navigate to the Tools section in the sidebar, or use the search functionality to find specific tool documentation. Each tool page includes IDs, owners, integration points, and automation workflows.

The site is automatically deployed to Cloudflare Pages on every push to the `main` branch. The primary URL is https://docs.pacing.agency, and it is protected by Cloudflare Access with Google OAuth for internal team members only.

Yes. Docusaurus supports MDX, which allows you to use React components in Markdown files. We have several reusable components available, including FAQ Structured Data and Callout components. See the Features section for available components and usage.

See [Repository Structure](/docs/docusaurus/docusaurus-repo-structure) for detailed instructions. Generally, create the component in `docusaurus/src/theme/MDXComponents/`, add docs in `docusaurus/docs/docusaurus/features/`, and update setup guidance if the feature is reusable.

Tool docs (`tools/*.md`) are automatically synced to the Docusaurus site and appear in the Tools section. Custom pages (`docusaurus/docs/*.md`) are standalone docs that do not sync from another source. Use tool docs for tool-level documentation and custom pages for guides, architecture docs, or other standalone content.

Related Documentation

• Benefits of Docusaurus - Why we chose Docusaurus
• Repository Structure - Project organisation and adding features
• Tool Categorization System - How tool categories and metadata work
• ToolMetadata Component - Visual metadata component for tool pages
• CategorySummary Component - Category page summary component
• ToolsOverview Component - Main tools page overview component
• FAQ Structured Data Component - Reusable FAQ component
• Callout Component - Reusable callout component for highlighted guidance
• Copy/Download Button - Copy and download page content feature
• Link Checker - Automated link validation tool
• Documentation Verification - Track documentation freshness
• Algolia Search - Full-text search with API-based indexing
• Setting Up New Repos - Guide for creating new Docusaurus sites
• Custom Page Template - Template for new custom docs pages
• Content Editing Prompt - Editorial rules and doc safety checks
• To-Do List - Planned features and recurring tasks