docusaurus-develop

常见 Docusaurus v3/v4 开发修复与配置调整。当您：(1) 正在搭建或维护 Docusaurus 站点；(2) 面临诸如 onBrokenMarkdownLinks 等已弃用配置选项的警告；(3) 在使用 pnpm 进行 swizzling 时，@docusaurus/theme-common 或 plugin-content-docs 出现“模块未找到”的错误；(4) 生成的文档出现应被抑制的断链警告；(5) 用户提出“Docusaurus 修复”、“Docusaurus 警告”、“修复 Docusaurus 配置”时，可使用此技能。

name: docusaurus-develop description: >- Common Docusaurus v3/v4 development fixes and configuration tweaks. Use when: (1) Setting up or maintaining a Docusaurus site, (2) Seeing warnings about deprecated config options like onBrokenMarkdownLinks, (3) Getting "Module not found" errors for @docusaurus/theme-common or plugin-content-docs when swizzling with pnpm, (4) Generated docs produce broken link warnings that should be suppressed, (5) User says 'docusaurus fix', 'docusaurus warnings', 'fix docusaurus config'.

Docusaurus Development Fixes

Tiny but important configuration tweaks for Docusaurus v3.x projects that prevent annoying warnings and build errors.

Fix 1: Suppress Broken Link Warnings for Generated Docs

When docs are auto-generated from external sources (e.g., Claude Code skills, API specs), they often contain internal references (references/foo.md) that don't resolve in Docusaurus. These warnings are noise.

In docusaurus.config.ts (or .js):

const config = {
  // Suppress broken link errors for generated docs with internal references
  onBrokenLinks: "ignore",

  markdown: {
    // v4-compatible location for onBrokenMarkdownLinks
    hooks: {
      onBrokenMarkdownLinks: "ignore",
    },
  },
};

Important: Do NOT use the top-level onBrokenMarkdownLinks option — it is deprecated since Docusaurus v3.6+ and will be removed in v4. Always place it under markdown.hooks.onBrokenMarkdownLinks instead.

Fix 2: Explicit Dependencies for pnpm + Swizzled Components

When swizzling Docusaurus theme components (e.g., DocItem/Content) under pnpm, imports like @docusaurus/theme-common and @docusaurus/plugin-content-docs/client fail with "Module not found" because pnpm's strict dependency resolution doesn't hoist transitive deps from @docusaurus/preset-classic.

Fix: install them explicitly.

bash

pnpm add @docusaurus/theme-common @docusaurus/plugin-content-docs

This is only needed when the project uses pnpm AND has swizzled components that import from these packages. npm/yarn hoist these automatically.