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's 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 - Built-in search across all documentation
• 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 - Real-time visibility into tool costs across categories (£582.56/month, £6,990.72/year total)
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 - Beautiful, color-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/annual costs
• ToolsOverview Component - Interactive expandable category cards on the main tools page with full cost overview
• Auto-sync Script - Automatically syncs tools/*.md files to categorised Docusaurus structure on every build
• Sections Configuration - Centralised config file for managing documentation sections (makes adding "Prompts" or "Processes" sections easy)
• 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 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 - Track last_verified dates and flag outdated documentation
• Algolia Search - Fast, full-text search with API-based indexing and Ask AI feature
• 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
• 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's 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 the FAQ Structured Data component. See the Features section for available components and how to use them.

See the [Repository Structure](./repo-structure.md) guide for detailed instructions. Generally, you'll create the component in `docusaurus/src/theme/MDXComponents/`, add documentation in `docusaurus/docs/docusaurus/features/`, and update the setup guide if it's a reusable feature.

Tool docs (`tools/*.md`) are automatically synced to the Docusaurus site and appear in the Tools section. Custom pages (`docusaurus/docs/*.md`) are standalone documentation pages that don't sync from anywhere. Use tool docs for tool 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
• 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
• To-Do List - Planned features and recurring tasks