Docusaurus config

Skill mcclowes/skills-docusaurus/skills/docusaurus-config

Use when working with docusaurus.config.js/ts files — validate the config structure, set required fields (title/url/baseUrl), fix URL and baseUrl formats, add presets and plugins, configure navbar/footer/theme settings, and move unknown keys into customFields. Triggers on tasks involving docusaurus.config.js, docusaurus.config.ts, site configuration, URL formats, presets, or theme config.From its SKILL.md

Install

npx -y skills add mcclowes/skills-docusaurus --skill docusaurus-config

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.3 KB, as published. Nobody here has run it

Docusaurus Config

Quick Start

Configuration lives in docusaurus.config.js or docusaurus.config.ts at project root.

import {Config} from '@docusaurus/types';

const config: Config = {
  title: 'My Site',           // Required
  url: 'https://example.com', // Required, no trailing /
  baseUrl: '/',               // Required, must start and end with /

  favicon: 'img/favicon.ico',
  organizationName: 'my-org',
  projectName: 'my-project',

  presets: [['@docusaurus/preset-classic', { /* options */ }]],
  themeConfig: { /* theme config */ },
  customFields: { /* unknown fields go here */ }
};

export default config;

Core Principles

Required: title, url, baseUrl are mandatory
Custom fields: Move every non-standard root-level key into customFields — see below
Validation: url no trailing slash, baseUrl must be /path/
Plugins/themes: Use string or [name, options] array format

Custom fields: move every non-standard key

Docusaurus only recognises a fixed set of root-level keys (title, url, baseUrl, favicon, organizationName, projectName, onBrokenLinks, i18n, presets, plugins, themes, themeConfig, markdown, staticDirectories, headTags, scripts, stylesheets, clientModules, ssrTemplate, titleDelimiter, noIndex, tagline, trailingSlash, future, customFields). Any other key at the root is a validation error.

When fixing a config, audit all root-level keys and move every unrecognised one into customFields — not just the first or most obvious one. A partial fix (moving one custom key but leaving another) still fails the build.

// ❌ Before — analyticsId AND supportEmail are both invalid at root
const config = {
  title: 'My Site',
  url: 'https://example.com',
  baseUrl: '/',
  analyticsId: 'UA-000000-2',      // not a Docusaurus key
  supportEmail: '[email protected]',    // not a Docusaurus key
};

// ✅ After — BOTH moved together into customFields
const config = {
  title: 'My Site',
  url: 'https://example.com',
  baseUrl: '/',
  customFields: {
    analyticsId: 'UA-000000-2',
    supportEmail: '[email protected]',
  },
};

Common Tasks

Before editing: Read current config to preserve format (JS/TS, ESM/CommonJS)

After editing: Verify required fields and URL formats, then validate the build:

Run npm run build — Docusaurus validates the full config and fails loudly on bad fields.
If it errors, read the message (it names the offending field), fix it, and re-run.
Once the build passes, restart the dev server (npm start) to confirm runtime behaviour.

A bad config breaks the whole site, so always confirm with a build before considering the change done.

Reference Files

See references/detailed-guide.md for comprehensive examples