Docusaurus Config

The file docusaurus.config.ts controls your entire site's metadata — title, URL, theme, plugins, and analytics.

This page covers the settings you'll want to change first.

---

File Location

docusaurus.config.ts

Located in the project root.

---

Site Identity

The most important settings:

const config: Config = {
  title: 'NOCTURNE',
  tagline: 'Documentation that feels premium. Built on Docusaurus.',
  url: 'https://nocturne.axcora.com',
  baseUrl: '/',
  organizationName: 'axcora',
  projectName: 'nocturne',
  ...
};

Field	What It Does	Example
title	Site title — appears in browser tab	NOCTURNE
tagline	Short description for SEO	Documentation that feels premium.
url	Your live site URL	https://nocturne.axcora.com
baseUrl	Path prefix — usually /	/
organizationName	GitHub org name	axcora
projectName	GitHub repo name	nocturne

When to change: Every time you set up Nocturne for a new project.

---

Favicon and Social Image

const config: Config = {
  favicon: 'img/nocturne-favicon.webp',
  ...
  themeConfig: {
    image: 'img/nocturne-og.webp',
  },
};

Field	What It Does
favicon	Icon in the browser tab
themeConfig.image	Social share image (Open Graph)

File location: Both go in static/img/.

Recommended sizes:

• Favicon — 32×32 or 64×64
• Social image — 1200×630

---

Dark Mode

Nocturne uses dark mode by default. You can change this:

themeConfig: {
  colorMode: {
    defaultMode: 'dark',       // 'dark' or 'light'
    disableSwitch: false,       // hide the toggle if true
    respectPrefersColorScheme: true,   // follow OS setting
  },
},

Setting	What It Does
defaultMode	'dark' or 'light'
disableSwitch	Hide the theme toggle
respectPrefersColorScheme	Follow the OS preference

---

Code Highlighting

Nocturne uses Prism for syntax highlighting:

themeConfig: {
  prism: {
    theme: prismThemes.github,
    darkTheme: prismThemes.dracula,
    additionalLanguages: ['python', 'bash', 'yaml', 'markdown', 'json'],
  },
},

Add languages if you use them in your docs. Common additions:

• typescript
• jsx
• tsx
• sql
• go
• rust

---

Google Search Console

Verify your site with Google Search Console:

themeConfig: {
  headTags: [
    {
      tagName: 'meta',
      attributes: {
        name: 'google-site-verification',
        content: 'YOUR_VERIFICATION_CODE',
      },
    },
  ],
},

Replace YOUR_VERIFICATION_CODE with the code from Google Search Console.

---

Blog Configuration

Control how the blog works:

presets: [
  [
    'classic',
    {
      blog: {
        showReadingTime: true,
        onUntruncatedBlogPosts: 'ignore',
      },
    },
  ],
],

Setting	What It Does
showReadingTime	Display estimated reading time
onUntruncatedBlogPosts	'ignore' to skip truncation warnings

---

Plugins

Nocturne ships with Pagefind search:

plugins: [
  [
    'docusaurus-plugin-pagefind',
    {
      forceLanguage: 'en',
      excludeSelectors: ['.navbar', 'footer'],
    },
  ],
],

Setting	What It Does
forceLanguage	Search language
excludeSelectors	Elements not indexed by search

Add more plugins as needed — Docusaurus has a huge ecosystem.

---

Full Example

Here's the complete docusaurus.config.ts for Nocturne:

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: 'NOCTURNE',
  tagline: 'Documentation that feels premium. Built on Docusaurus.',
  favicon: 'img/nocturne-favicon.webp',

  future: { v4: true },

  url: 'https://nocturne.axcora.com',
  baseUrl: '/',
  organizationName: 'axcora',
  projectName: 'nocturne',

  onBrokenLinks: 'warn',

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

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

  plugins: [
    [
      'docusaurus-plugin-pagefind',
      {
        forceLanguage: 'en',
        excludeSelectors: ['.navbar', 'footer'],
      },
    ],
  ],

  themeConfig: {
    image: 'img/nocturne-og.webp',
    colorMode: {
      defaultMode: 'dark',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
      additionalLanguages: ['python', 'bash', 'yaml', 'markdown', 'json'],
    },
    headTags: [
      {
        tagName: 'meta',
        attributes: {
          name: 'google-site-verification',
          content: 'YOUR_VERIFICATION_CODE',
        },
      },
    ],
  } satisfies Preset.ThemeConfig,
};

export default config;

---

After Editing

1. Save the file
2. Run npm start to see changes locally
3. Run npm run build before deploying

---

Troubleshooting

Config changes don't appear

1. Make sure you saved the file
2. Restart the dev server: Ctrl + C then npm start
3. Check the terminal for TypeScript errors

TypeScript error in config

1. Check the syntax — commas, brackets
2. Check the Docusaurus docs for the correct field name
3. Run npx tsc --noEmit to see detailed errors

Site URL is wrong

The url field must match your production URL. Update it before deploying.

---

What's Next?

Now let's configure the sidebar.

👉 Next: Sidebar Config →