documentation-docusaurus/references/docusaurus-config-template.md

Docusaurus Config Template — Modern Dark Theme

Full docusaurus.config.ts for a modern dark-first docs site with:

• draw.io plugin (docusaurus-plugin-drawio)
• Mermaid C4 diagrams (@docusaurus/theme-mermaid)
• Dark mode default
• Prism oneDark theme
• Announcement bar
• Sidebar TOC config

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: 'My Project',
  tagline: 'Documentation tagline',
  favicon: 'img/favicon.ico',

  url: 'https://docs.example.com',
  baseUrl: '/',

  organizationName: 'org-name',
  projectName: 'documentation',

  onBrokenLinks: 'throw',
  markdown: {
    hooks: {
      onBrokenMarkdownLinks: 'warn',
    },
    mermaid: true,
  },

  i18n: { defaultLocale: 'en', locales: ['en'] },

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

  plugins: ['docusaurus-plugin-drawio'],

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          editUrl: 'https://gitea.lego-cloud.eu/ORG/REPO/src/branch/main/',
          showLastUpdateTime: true,
          showLastUpdateAuthor: true,
        },
        blog: {
          showReadingTime: true,
          blogTitle: 'Changelog',
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    colorMode: {
      defaultMode: 'dark',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },

    announcementBar: {
      id: 'wip',
      content: '🚧 Under active development.',
      backgroundColor: '#1a1a2e',
      textColor: '#818cf8',
      isCloseable: true,
    },

    navbar: {
      title: 'My Project',
      hideOnScroll: true,
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'docsSidebar',
          position: 'left',
          label: 'Docs',
        },
        {
          href: 'https://gitea.lego-cloud.eu/ORG',
          position: 'right',
          label: 'Gitea ↗',
        },
      ],
    },

    footer: {
      style: 'dark',
      copyright: `© ${new Date().getFullYear()} My Project · Built by Jarvis`,
    },

    prism: {
      theme: prismThemes.oneDark,
      darkTheme: prismThemes.oneDark,
      additionalLanguages: ['bash', 'python', 'sql', 'yaml', 'json', 'typescript', 'docker'],
    },

    mermaid: {
      theme: { light: 'neutral', dark: 'dark' },
    },

    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 4,
    },
  } satisfies Preset.ThemeConfig,
};

export default config;

Required packages

npx pnpm add @docusaurus/theme-mermaid docusaurus-plugin-drawio raw-loader

Pitfalls

• onBrokenMarkdownLinks moved to markdown.hooks.onBrokenMarkdownLinks in Docusaurus v3 — using siteConfig.onBrokenMarkdownLinks triggers a deprecation warning
• Remove blog from navbar if you have no blog posts — broken link on build
• to: 'https://...' does NOT work for external links in navbar; use href: instead