plugin-content-docs: Docs Plugin Configuration Reference

@docusaurus/plugin-content-docs is the engine behind the Docusaurus documentation system. It reads Markdown and MDX files from your filesystem, builds a versioned content graph, generates sidebar navigation, and creates all documentation routes. It is included in @docusaurus/preset-classic and does not need to be installed separately when using the preset.

Installation

npm2yarn

npm install --save @docusaurus/plugin-content-docs

If you use @docusaurus/preset-classic, configure this plugin through the docs preset key instead of adding it to the plugins array.

Configuration options

Option	Type	Default	Description
`path`	`string`	`'docs'`	Path to the docs content directory on the filesystem, relative to the site directory.
`routeBasePath`	`string`	`'docs'`	URL route for the docs section. Do not include a trailing slash. Use `/` to serve docs from the site root.
`tagsBasePath`	`string`	`'tags'`	URL route for the tags list page, prepended to `routeBasePath`.
`editUrl`	`string \| EditUrlFunction`	`undefined`	Base URL for “Edit this page” links. A function receives `{version, versionDocsDirPath, docPath, permalink, locale}` and returns a URL string. Omit to disable edit links.
`editLocalizedFiles`	`boolean`	`false`	When `true`, edit links target the localized file rather than the original. Ignored when `editUrl` is a function.
`editCurrentVersion`	`boolean`	`false`	When `true`, edit links always target the current version even when browsing older versions. Ignored when `editUrl` is a function.
`sidebarPath`	`false \| string`	`undefined`	Path to the sidebars configuration file. Use `false` to disable sidebars entirely, or omit to generate a fully autogenerated sidebar.
`sidebarCollapsible`	`boolean`	`true`	Whether sidebar categories are collapsible by default.
`sidebarCollapsed`	`boolean`	`true`	Whether sidebar categories start collapsed by default.
`sidebarItemsGenerator`	`SidebarGenerator`	built-in	Function that replaces `autogenerated` sidebar items with real items.
`numberPrefixParser`	`boolean \| PrefixParser`	built-in	Controls extraction of numeric prefixes from filenames for ordering. Set `false` to disable, `true` to use the default parser.
`include`	`string[]`	`['*/.{md,mdx}']`	Glob patterns for Markdown files to include, relative to the content path.
`exclude`	`string[]`	see example	Glob patterns for Markdown files to exclude. Refines the `include` list.
`showLastUpdateAuthor`	`boolean`	`false`	Display the author of the last git commit for each doc.
`showLastUpdateTime`	`boolean`	`false`	Display the date of the last git commit for each doc. Requires full git history — use `fetch-depth: 0` on GitHub Actions.
`breadcrumbs`	`boolean`	`true`	Show breadcrumb navigation at the top of doc pages.
`disableVersioning`	`boolean`	`false`	Force the site to show only the current version, even if versioned docs exist.
`includeCurrentVersion`	`boolean`	`true`	Include the current (unreleased) version in the site.
`lastVersion`	`string`	first in `versions.json`	The version shown by default and used for docs navbar items.
`onlyIncludeVersions`	`string[]`	all versions	Restrict which versions are built.
`versions`	`VersionsConfig`	`{}`	Per-version overrides for path, label, banner, badge, and index behavior.
`tags`	`string \| false \| null`	`'tags.yml'`	Path to a YAML file defining pre-defined tags, relative to the docs version content directory.
`onInlineTags`	`'ignore' \| 'log' \| 'warn' \| 'throw'`	`'warn'`	Behavior when docs use tags not declared in the pre-defined tags file.
`docItemComponent`	`string`	`'@theme/DocItem'`	Main doc container component (TOC, pagination, etc.).
`docRootComponent`	`string`	`'@theme/DocRoot'`	Parent of all doc pages with sidebars.
`docVersionRootComponent`	`string`	`'@theme/DocVersionLayout'`	Parent of all pages in a single version.
`docsRootComponent`	`string`	`'@theme/DocsRoot'`	Top-level parent of all docs plugin pages across versions.
`docTagsListComponent`	`string`	`'@theme/DocTagsListPage'`	Root component of the tags list page.
`docTagDocListComponent`	`string`	`'@theme/DocTagDocListPage'`	Root component of the “docs with tag X” page.
`docCategoryGeneratedIndexComponent`	`string`	`'@theme/DocCategoryGeneratedIndexPage'`	Root component for generated category index pages.
`remarkPlugins`	`any[]`	`[]`	Remark plugins passed to the MDX processor.
`rehypePlugins`	`any[]`	`[]`	Rehype plugins passed to the MDX processor.
`recmaPlugins`	`any[]`	`[]`	Recma plugins passed to the MDX processor.
`beforeDefaultRemarkPlugins`	`any[]`	`[]`	Remark plugins injected before Docusaurus’s built-in Remark plugins.
`beforeDefaultRehypePlugins`	`any[]`	`[]`	Rehype plugins injected before Docusaurus’s built-in Rehype plugins.

Type definitions

EditUrlFunction

type EditUrlFunction = (params: {
  version: string;
  versionDocsDirPath: string;
  docPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

PrefixParser

type PrefixParser = (filename: string) => {
  filename: string;
  numberPrefix?: number;
};

SidebarGenerator

type SidebarGenerator = (generatorArgs: {
  item: {type: 'autogenerated'; dirName: string};
  version: {contentPath: string; versionName: string};
  docs: {
    id: string;
    title: string;
    frontMatter: DocFrontMatter & Record<string, unknown>;
    source: string;
    sourceDirName: string;
    sidebarPosition?: number | undefined;
  }[];
  numberPrefixParser: PrefixParser;
  isCategoryIndex: CategoryIndexMatcher;
  categoriesMetadata: {[filePath: string]: CategoryMetadata};
  defaultSidebarItemsGenerator: SidebarGenerator;
}) => Promise<SidebarItem[]>;

VersionsConfig

type VersionConfig = {
  path?: string;
  label?: string;
  banner?: 'none' | 'unreleased' | 'unmaintained';
  badge?: boolean;
  noIndex?: boolean;
  className?: string;
};

type VersionsConfig = {[versionName: string]: VersionConfig};

Example configuration

Preset options (recommended)
Standalone plugin

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs',
          routeBasePath: 'docs',
          sidebarPath: './sidebars.js',
          editUrl: ({versionDocsDirPath, docPath}) =>
            `https://github.com/your-org/your-repo/edit/main/website/${versionDocsDirPath}/${docPath}`,
          showLastUpdateAuthor: true,
          showLastUpdateTime: true,
          breadcrumbs: true,
          includeCurrentVersion: true,
          versions: {
            current: {
              label: 'Next (unreleased)',
              banner: 'unreleased',
            },
          },
        },
      },
    ],
  ],
};

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: './sidebarsCommunity.js',
      },
    ],
  ],
};

Use the id option when running multiple instances of plugin-content-docs to give each instance a unique identifier.

Markdown front matter

Individual doc files can override plugin defaults using front matter fields.

Field	Type	Default	Description
`id`	`string`	file path without extension	Unique document ID used for sidebar references and cross-links.
`title`	`string`	Markdown heading or `id`	Document title shown in sidebar, page heading, and metadata.
`sidebar_label`	`string`	`title`	Text shown in the sidebar for this document.
`sidebar_position`	`number`	auto	Controls ordering within an autogenerated sidebar group.
`sidebar_class_name`	`string`	`undefined`	Additional CSS class applied to this item’s sidebar label.
`sidebar_custom_props`	`object`	`undefined`	Custom props passed through to the sidebar item.
`displayed_sidebar`	`string`	`undefined`	Force a specific sidebar to show when viewing this doc.
`pagination_label`	`string`	`sidebar_label` or `title`	Text used in next/previous pagination buttons.
`pagination_next`	`string \| null`	next in sidebar	Doc ID to link in the “Next” button. Use `null` to disable.
`pagination_prev`	`string \| null`	previous in sidebar	Doc ID to link in the “Previous” button. Use `null` to disable.
`hide_title`	`boolean`	`false`	Hide the front matter title from the page (does not affect Markdown headings).
`hide_table_of_contents`	`boolean`	`false`	Hide the right-hand table of contents panel.
`toc_min_heading_level`	`number`	`2`	Minimum heading level shown in the TOC (2–6).
`toc_max_heading_level`	`number`	`3`	Maximum heading level shown in the TOC (2–6).
`slug`	`string`	file path	Custom URL path for the document.
`tags`	`Tag[]`	`undefined`	Tags to apply to this document. Strings may reference keys from `tags.yml`.
`keywords`	`string[]`	`undefined`	`<meta name="keywords">` content for search engines.
`description`	`string`	first line of content	`<meta name="description">` and OpenGraph description.
`image`	`string`	`undefined`	OpenGraph `og:image` URL for social link previews.
`draft`	`boolean`	`false`	Draft docs are only available in development mode.
`unlisted`	`boolean`	`false`	Unlisted docs are hidden from navigation and sitemaps but remain accessible via direct URL.
`custom_edit_url`	`string \| null`	computed from `editUrl` option	Override the edit link for this specific document. `null` disables it.
`parse_number_prefixes`	`boolean`	plugin option	Override whether numeric prefix parsing applies to this doc.
`last_update`	`FrontMatterLastUpdate`	`undefined`	Manually override the last update author or date.

docs/intro.md

---
id: intro
title: Getting Started
sidebar_label: Introduction
sidebar_position: 1
tags: [quickstart, overview]
description: A quick introduction to the project and how to get started.
---

# Getting Started

Welcome to the docs!

Versioning

When you run docusaurus docs:version 1.0.0, Docusaurus snapshots your current docs/ folder into versioned_docs/version-1.0.0/. The versions option lets you customize how each version is displayed:

versions: {
  current: {
    label: 'Next (main branch)',
    banner: 'unreleased',
  },
  '2.0.0': {
    label: '2.0.0 (stable)',
    banner: 'none',
  },
  '1.0.0': {
    label: '1.0.0 (legacy)',
    banner: 'unmaintained',
  },
},

i18n

Translated docs live under website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]/. For multi-instance setups, the path uses docusaurus-plugin-content-docs-[pluginId] instead.

Core

Plugins

Themes

Plugin Development

plugin-content-docs: Docs Plugin Configuration Reference

Installation

Configuration options

Type definitions

Example configuration

Markdown front matter

Versioning

i18n

Build docs developers (and LLMs) love

Core

Plugins

Themes

Plugin Development

Documentation Index

​Installation

​Configuration options

​Type definitions

​Example configuration

​Markdown front matter

​Versioning

​i18n

Build docs developers (and LLMs) love

Installation

Configuration options

Type definitions

Example configuration

Markdown front matter

Versioning

i18n