📦 plugin-content-docs

Provides the Docs functionality and is the default docs plugin for Docusaurus.

Installation

npm

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

Yarn

yarn add @docusaurus/plugin-content-docs

pnpm

pnpm add @docusaurus/plugin-content-docs

Bun

bun add @docusaurus/plugin-content-docs

tip

If you use the preset @docusaurus/preset-classic, you don't need to install this plugin as a dependency.

You can configure this plugin through the preset options.

Configuration

Accepted fields:

Name	Type	Default	Description
path	string	'docs'	Path to the docs content directory on the file system, relative to site directory.
editUrl	string | EditUrlFunction	undefined	Base URL to edit your site. The final URL is computed by editUrl + relativeDocPath. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links.
editLocalizedFiles	boolean	false	The edit URL will target the localized file, instead of the original unlocalized file. Ignored when editUrl is a function.
editCurrentVersion	boolean	false	The edit URL will always target the current version doc instead of older versions. Ignored when editUrl is a function.
routeBasePath	string	'docs'	URL route for the docs section of your site. DO NOT include a trailing slash. Use / for shipping docs without base path.
tagsBasePath	string	'tags'	URL route for the tags list page of your site. It is prepended to the routeBasePath.
include	string[]	['**/*.{md,mdx}']	Array of glob patterns matching Markdown files to be built, relative to the content path.
exclude	string[]	See example configuration	Array of glob patterns matching Markdown files to be excluded. Serves as refinement based on the include option.
sidebarPath	false | string	undefined	Path to a sidebars configuration file, loaded in a Node.js context. Use false to disable sidebars, or undefined to create a fully autogenerated sidebar.
sidebarCollapsible	boolean	true	Whether sidebar categories are collapsible by default. See also Collapsible categories
sidebarCollapsed	boolean	true	Whether sidebar categories are collapsed by default. See also Expanded categories by default
sidebarItemsGenerator	SidebarGenerator	Omitted	Function used to replace the sidebar items of type 'autogenerated' with real sidebar items (docs, categories, links...). See also Customize the sidebar items generator
numberPrefixParser	boolean | PrefixParser	Omitted	Custom parsing logic to extract number prefixes from file names. Use false to disable this behavior and leave the docs untouched, and true to use the default parser. See also Using number prefixes
docsRootComponent	string	'@theme/DocsRoot'	Parent component of all the docs plugin pages (including all versions). Stays mounted when navigation between docs pages and versions.
docVersionRootComponent	string	'@theme/DocVersionLayout'	Parent component of all docs pages of an individual version (doc pages with sidebars, tags pages). Stays mounted when navigation between pages of that specific version.
docRootComponent	string	'@theme/DocRoot'	Parent component of all doc pages with sidebars (regular docs pages, category generated index pages). Stays mounted when navigation between such pages.
docItemComponent	string	'@theme/DocItem'	Main doc container, with TOC, pagination, etc.
docTagsListComponent	string	'@theme/DocTagsListPage'	Root component of the tags list page
docTagDocListComponent	string	'@theme/DocTagDocListPage'	Root component of the "docs containing tag X" page.
docCategoryGeneratedIndexComponent	string	'@theme/DocCategoryGeneratedIndexPage'	Root component of the generated category index page.
remarkPlugins	any[]	[]	Remark plugins passed to MDX.
rehypePlugins	any[]	[]	Rehype plugins passed to MDX.
recmaPlugins	any[]	[]	Recma plugins passed to MDX.
beforeDefaultRemarkPlugins	any[]	[]	Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins.
beforeDefaultRehypePlugins	any[]	[]	Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins.
showLastUpdateAuthor	boolean	false	Whether to display the author who last updated the doc.
showLastUpdateTime	boolean	false	Only for Markdown pages. Whether to display the last date the doc was updated. This requires access to git history during the build, so will not work correctly with shallow clones (a common default for CI systems). With GitHub actions/checkout, use fetch-depth: 0. When deploying to Vercel, set the environment variable VERCEL_DEEP_CLONE=true.
breadcrumbs	boolean	true	Enable or disable the breadcrumbs on doc pages.
disableVersioning	boolean	false	Explicitly disable versioning even when multiple versions exist. This will make the site only include the current version. Will error if includeCurrentVersion: false and disableVersioning: true.
includeCurrentVersion	boolean	true	Include the current version of your docs.
lastVersion	string	First version in versions.json	The version navigated to in priority and displayed by default for docs navbar items.
onlyIncludeVersions	string[]	All versions available	Only include a subset of all available versions.
versions	VersionsConfig	{}	Independent customization of each version's properties.
tags	string | false | null | undefined	tags.yml	Path to a YAML file listing pre-defined tags. Relative to the docs version content directories.
onInlineTags	'ignore' | 'log' | 'warn' | 'throw'	warn	The plugin behavior when docs contain inline tags (not appearing in the list of pre-defined tags, usually docs/tags.yml).

Types

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: {
  /** The sidebar item with type "autogenerated" to be transformed. */
  item: {type: 'autogenerated'; dirName: string};
  /** Useful metadata for the version this sidebar belongs to. */
  version: {contentPath: string; versionName: string};
  /** All the docs of that version (unfiltered). */
  docs: {
    id: string;
    title: string;
    frontMatter: DocFrontMatter & Record<string, unknown>;
    source: string;
    sourceDirName: string;
    sidebarPosition?: number | undefined;
  }[];
  /** Number prefix parser configured for this plugin. */
  numberPrefixParser: PrefixParser;
  /** The default category index matcher which you can override. */
  isCategoryIndex: CategoryIndexMatcher;
  /**
   * key is the path relative to the doc content directory, value is the
   * category metadata file's content.
   */
  categoriesMetadata: {[filePath: string]: CategoryMetadata};
  /**
   * Useful to re-use/enhance the default sidebar generation logic from
   * Docusaurus.
   */
  defaultSidebarItemsGenerator: SidebarGenerator;
  // Returns an array of sidebar items — same as what you can declare in
  // sidebars.js, except for shorthands. See https://docusaurus.io/docs/sidebar/items
}) => Promise<SidebarItem[]>;

type CategoryIndexMatcher = (param: {
  /** The file name, without extension */
  fileName: string;
  /**
   * The list of directories, from lowest level to highest.
   * If there's no dir name, directories is ['.']
   */
  directories: string[];
  /** The extension, with a leading dot */
  extension: string;
}) => boolean;

VersionsConfig

type VersionConfig = {
  /**
   * The base path of the version, will be appended to `baseUrl` +
   * `routeBasePath`.
   */
  path?: string;
  /** The label of the version to be used in badges, dropdowns, etc. */
  label?: string;
  /** The banner to show at the top of a doc of that version. */
  banner?: 'none' | 'unreleased' | 'unmaintained';
  /** Show a badge with the version label at the top of each doc. */
  badge?: boolean;
  /** Prevents search engines from indexing this version */
  noIndex?: boolean;
  /** Add a custom class name to the <html> element of each doc */
  className?: string;
};

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

Example configuration

You can configure this plugin through preset options or plugin options.

tip

Most Docusaurus users configure this plugin through the preset options.

Preset options

If you use a preset, configure this plugin through the preset options:

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs',
          breadcrumbs: true,
          // Simple use-case: string editUrl
          // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
          // Advanced use-case: functional editUrl
          editUrl: ({versionDocsDirPath, docPath}) =>
            `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`,
          editLocalizedFiles: false,
          editCurrentVersion: false,
          routeBasePath: 'docs',
          include: ['**/*.md', '**/*.mdx'],
          exclude: [
            '**/_*.{js,jsx,ts,tsx,md,mdx}',
            '**/_*/**',
            '**/*.test.{js,jsx,ts,tsx}',
            '**/__tests__/**',
          ],
          sidebarPath: 'sidebars.js',
          async sidebarItemsGenerator({
            defaultSidebarItemsGenerator,
            numberPrefixParser,
            item,
            version,
            docs,
            isCategoryIndex,
          }) {
            // Use the provided data to generate a custom sidebar slice
            return [
              {type: 'doc', id: 'intro'},
              {
                type: 'category',
                label: 'Tutorials',
                items: [
                  {type: 'doc', id: 'tutorial1'},