documentation-docusaurus/references/config-reference.md

Configuration Reference

Essential docusaurus.config.ts options. Not exhaustive—see Docusaurus docs for everything.

---

Minimum Viable Config

const config = {
  title: 'Project Name',
  url: 'https://docs.example.com',
  baseUrl: '/',

  presets: [
    ['classic', {
      docs: { routeBasePath: '/' },  // Docs at root
      blog: false,                    // Disable if not using
      theme: { customCss: './src/css/custom.css' },
    }],
  ],
};

My opinion: Start minimal. Add complexity only when you need it.

---

The Options That Actually Matter

Site Identity

title: 'Your Project',           // Browser tab, search results
tagline: 'One sentence pitch',   // Shows in default homepage
favicon: 'img/favicon.ico',

URLs

url: 'https://docs.example.com', // Production URL (no trailing slash)
baseUrl: '/',                    // Usually '/' unless in subdirectory
trailingSlash: false,            // Pick one and stick with it

Opinion: trailingSlash: false. It's cleaner and most platforms handle it correctly.

Build Behavior

onBrokenLinks: 'throw',           // Fail build on broken links
onBrokenMarkdownLinks: 'throw',   // Same for markdown links

Opinion: Always throw in production. warn during development is OK.

---

Preset: Classic (Use This)

presets: [
  ['classic', {
    docs: {
      sidebarPath: './sidebars.ts',
      routeBasePath: '/',           // Docs as homepage
      editUrl: 'https://github.com/org/repo/edit/main/',
      showLastUpdateTime: true,     // Shows git commit time
    },
    blog: {
      showReadingTime: true,
      blogSidebarCount: 'ALL',
    },
    theme: {
      customCss: './src/css/custom.css',
    },
  }],
],

Docs-Only Mode

Set routeBasePath: '/' and either blog: false or keep blog at /blog.

---

Theme Config: What Readers See

Navbar

themeConfig: {
  navbar: {
    title: 'Project',
    logo: { alt: 'Logo', src: 'img/logo.svg' },
    items: [
      { type: 'docSidebar', sidebarId: 'docs', label: 'Docs' },
      { to: '/blog', label: 'Blog' },
      { href: 'https://github.com/...', label: 'GitHub', position: 'right' },
    ],
  },
}

Opinion: Keep navbar items under 5. More than that, use dropdowns.

Color Mode

colorMode: {
  defaultMode: 'light',           // Or 'dark'
  respectPrefersColorScheme: true, // Honor system preference
},

Opinion: Always respectPrefersColorScheme: true. Don't force your preference.

Sidebar Behavior

docs: {
  sidebar: {
    hideable: true,              // Let users collapse it
    autoCollapseCategories: true, // Only one category expanded
  },
},

Search (Algolia)

algolia: {
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',  // Public search-only key
  indexName: 'YOUR_INDEX',
},

Apply at Algolia DocSearch. It's free for open source.

---

Plugins Worth Adding

Client-Side Redirects

plugins: [
  ['@docusaurus/plugin-client-redirects', {
    redirects: [
      { from: '/old-page', to: '/new-page' },
    ],
  }],
],

Use for moved pages. Don't leave 404s.

Ideal Image

['@docusaurus/plugin-ideal-image', {
  quality: 85,
  max: 1030,
  min: 640,
}],

Auto-generates responsive images. Worth it for image-heavy docs.

---

Things I Never Configure

These defaults are fine:

• i18n (unless you actually have translations ready)
• onDuplicateRoutes (the default warn is fine)
• staticDirectories (default static works)
• titleDelimiter (the | is universal)

Don't add config for things you're not using. It's clutter.

---

Config Anti-Patterns

Don't: Copy entire example configs and modify Do: Start minimal, add what you need

Don't: Set onBrokenLinks: 'ignore' to "fix" build errors Do: Actually fix the broken links

Don't: Add customFields unless you're using them in code Do: Keep config lean

---

Environment Variables

For values that change between environments:

const config = {
  url: process.env.SITE_URL || 'http://localhost:3000',
  customFields: {
    apiUrl: process.env.API_URL,
  },
};

Access in components:

import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const { siteConfig } = useDocusaurusContext();
const apiUrl = siteConfig.customFields.apiUrl;