Skip to main content

Setting Up a New Docusaurus Repository

This guide walks you through setting up a new Docusaurus repository with all the features and best practices from the Pacing Agency tech stack documentation.

Features Included​

  • ✅ Tool Categorization System - Automatic organization of tools by category with cost tracking
  • ✅ ToolMetadata Component - Visual metadata cards on tool pages
  • ✅ CategorySummary Component - Category page summaries with aggregated costs
  • ✅ ToolsOverview Component - Interactive expandable overview on main tools page
  • ✅ Sections Configuration - Centralized management of documentation sections
  • ✅ Mermaid Diagrams - Visual diagramming support
  • ✅ FAQ Structured Data - SEO-friendly FAQ component with toggleable structured data
  • ✅ Auto-sync Script - Automatic sync of tool documentation with categorization
  • ✅ Feature Toggles - Configurable features for internal vs external documentation

Prerequisites​

  • Node.js >= 20.0
  • npm (comes with Node.js)
  • Git
  • A GitHub repository (for deployment)

Step 1: Initialize Docusaurus​

npx create-docusaurus@latest my-docs classic
cd my-docs

Step 2: Install Dependencies​

npm install @docusaurus/theme-mermaid

Step 3: Configure Docusaurus​

Update docusaurus.config.ts:

import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'Your Documentation Site',
  tagline: 'Documentation for your project',
  url: 'https://your-site.com',
  baseUrl: '/',
  
  // Feature flags
  customFields: {
    features: {
      documentationType: 'internal', // or 'external' for public sites
      enableFAQStructuredData: true, // Enable FAQ structured data
      enableMermaid: true, // Enable Mermaid diagrams
    },
  },

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
        },
        blog: {
          showReadingTime: true,
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      } satisfies Preset.Options,
    ],
  ],

  themes: ['@docusaurus/theme-mermaid'],

  markdown: {
    mermaid: true,
  },

  themeConfig: {
    mermaid: {
      theme: {
        light: 'default',
        dark: 'dark',
      },
      options: {
        maxTextSize: 50000,
      },
    },
  } satisfies Preset.ThemeConfig,
};

export default config;

Step 4: Add FAQ Structured Data Component​

  1. Create directory structure:
mkdir -p src/theme/MDXComponents/FAQStructuredData

  1. Copy component files:

    • Copy src/theme/MDXComponents/FAQStructuredData/index.js
    • Copy src/theme/MDXComponents/FAQStructuredData/types.d.ts

    From this repository or create them based on the FAQ Structured Data documentation.

Step 5: Add Auto-Sync Script (Optional)​

If you want to auto-sync documentation from a tools/ directory:

  1. Create sync script:
mkdir -p scripts

  1. Copy scripts/sync-tools.cjs from this repository

  2. Add to package.json:

{
  "scripts": {
    "prebuild": "node scripts/sync-tools.cjs",
    "build": "docusaurus build",
    "start": "docusaurus start"
  }
}

Step 6: Feature Toggle Configuration​

Internal Documentation​

For internal documentation (no SEO needed):

// docusaurus.config.ts
customFields: {
  features: {
    documentationType: 'internal',
    enableFAQStructuredData: false, // No structured data needed
    enableMermaid: true,
  },
},

Usage in MDX:

import FAQStructuredData from '@site/src/theme/MDXComponents/FAQStructuredData';

<FAQStructuredData 
  faqs={faqs} 
  includeStructuredData={false} 
/>

External/Public Documentation​

For public-facing sites (SEO important):

// docusaurus.config.ts
customFields: {
  features: {
    documentationType: 'external',
    enableFAQStructuredData: true, // Enable structured data for SEO
    enableMermaid: true,
  },
},

Usage in MDX:

import FAQStructuredData from '@site/src/theme/MDXComponents/FAQStructuredData';

<FAQStructuredData 
  faqs={faqs} 
  includeStructuredData={true} 
/>

Step 7: Create Feature Documentation​

Create a docs/features/ directory and add:

  • faq-structured-data.md - FAQ component documentation
  • mermaid-diagrams.md - Mermaid diagram guide (or link to tools/mermaid.md)
  • setup-new-repo.md - This file

Step 8: Deployment​

Cloudflare Pages​

  1. Connect repository to Cloudflare Pages
  2. Configure build settings:
    • Framework preset: Docusaurus
    • Build command: npm run build
    • Build directory: build
    • Root directory: docusaurus (if using monorepo structure)

GitHub Pages​

  1. Install gh-pages:
npm install --save-dev gh-pages
  1. Add deploy script to package.json:
{
  "scripts": {
    "deploy": "docusaurus deploy"
  }
}
  1. Configure docusaurus.config.ts:
const config: Config = {
  // ... other config
  organizationName: 'your-org',
  projectName: 'your-repo',
};

Feature Checklist​

Use this checklist when setting up a new repository:

  • Docusaurus initialized
  • Mermaid theme installed and configured
  • FAQ Structured Data component added
  • Feature flags configured in docusaurus.config.ts
  • Auto-sync script added (if needed)
  • Feature documentation created
  • Deployment configured (Cloudflare Pages or GitHub Pages)
  • Structured data tested (for external sites)

Testing Features​

Test Mermaid Diagrams​

Create a test page with a Mermaid diagram:

# Test Mermaid

```mermaid
graph TD
    A[Start] --> B[End]

### Test FAQ Component

Create a test page with FAQs:

```mdx
import FAQStructuredData from '@site/src/theme/MDXComponents/FAQStructuredData';

export const faqs = [
  {
    question: 'Test Question?',
    answer: 'Test Answer',
  },
];

<FAQStructuredData faqs={faqs} />

Test Structured Data (External Sites)​

  1. Deploy your site
  2. Visit Google Rich Results Test
  3. Enter your page URL
  4. Verify FAQ structured data is detected

Troubleshooting​

FAQ Component Not Found​

  • Ensure the component files are in src/theme/MDXComponents/FAQStructuredData/
  • Check the import path matches your directory structure
  • Verify the component is exported correctly

Mermaid Diagrams Not Rendering​

  • Verify @docusaurus/theme-mermaid is installed
  • Check themes: ['@docusaurus/theme-mermaid'] is in config
  • Ensure markdown: { mermaid: true } is set

Structured Data Not Valid​

  • Use Google Rich Results Test to validate
  • Check that includeStructuredData={true} is set
  • Verify FAQ objects have both question and answer properties

Next Steps​

  1. Customize theme - Update colors, fonts, and branding
  2. Add content - Create your documentation pages
  3. Configure search - Set up Algolia DocSearch (optional)
  4. Set up CI/CD - Automate deployments
  5. Add analytics - Configure tracking (if needed)