docusaurus/website/docs/api/plugins/plugin-content-docs.md

---
sidebar_position: 1
id: plugin-content-docs
title: '📦 plugin-content-docs'
slug: '/api/plugins/@docusaurus/plugin-content-docs'
---

import APITable from '@site/src/components/APITable';

Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus.

## Installation {#installation}

```bash npm2yarn
npm install --save @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 {#configuration}

Accepted fields:

<APITable>

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `string` | `'docs'` | Path to data on filesystem relative to site dir. |
| `editUrl` | <code>string \| EditUrlFunction</code> | `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}']` | Matching files will be included and processed. |
| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. |
| `sidebarPath` | <code>false \| string</code> | `undefined` (creates autogenerated sidebar) | Path to sidebar configuration. |
| `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. See also [Collapsible categories](/docs/sidebar#collapsible-categories) |
| `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. See also [Expanded categories by default](/docs/sidebar#expanded-categories-by-default) |
| `sidebarItemsGenerator` | `SidebarGenerator` | _Omitted_ | Function used to replace the sidebar items of type `'autogenerated'` by real sidebar items (docs, categories, links...). See also [Customize the sidebar items generator](/docs/sidebar#customize-the-sidebar-items-generator) |
| `numberPrefixParser` | <code>boolean \| PrefixParser</code> | _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](/docs/sidebar#using-number-prefixes) |
| `docLayoutComponent` | `string` | `'@theme/DocPage'` | Root Layout component of each doc page. |
| `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" 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. |
| `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` | Whether to display the last date the doc was updated. |
| `disableVersioning` | `boolean` | `false` | Explicitly disable the versioning feature even with versions. This will only include the "current" version (the `/docs` directory). |
| `includeCurrentVersion` | `boolean` | `true` | Include the "current" version of your docs (the `/docs` directory). <br /> Tip: turn it off if the current version is a work-in-progress, not ready to be published. |
| `lastVersion` | `string` | `current` (alias for the first version to appear in `versions.json` and at the "root" (docs have `path=/docs/myDoc`)) | Set the version navigated to in priority on versioned sites and the one displayed by default in docs navbar items. <br /> Note: the path and label of the last version are configurable. <br /> Tip: `lastVersion: 'current'` makes sense in many cases. |
| `versions` | `Versions` | `{}` | Independent customization of each version's properties. |
| `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. <br /> Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews. |

</APITable>

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

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

type SidebarGenerator = (generatorArgs: {
  item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated"
  version: {contentPath: string; versionName: string}; // the current version
  docs: Array<{
    id: string;
    frontMatter: DocFrontMatter & Record<string, unknown>;
    source: string;
    sourceDirName: string;
    sidebarPosition?: number | undefined;
  }>; // all the docs of that version (unfiltered)
  numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin
  defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus
}) => Promise<SidebarItem[]>;

type Versions = Record<
  string, // the version's ID
  {
    label: string; // the label of the version
    path: string; // the route path of the version
    banner: 'none' | 'unreleased' | 'unmaintained'; // the banner to show at the top of a doc of that version
    badge: boolean; // show a badge with the version name at the top of a doc of that version
    className; // add a custom className to the <html> element when browsing docs of that version
  }
>;
```

### Example configuration {#ex-config}

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

:::tip

Most Docusaurus users configure this plugin through the preset options.

:::

```js config-tabs
// preset option name: docs
// plugin name: @docusaurus/plugin-content-docs

const config = {
  path: 'docs',
  // 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,
  }) {
    // Use the provided data to generate a custom sidebar slice
    return [
      {type: 'doc', id: 'intro'},
      {
        type: 'category',
        label: 'Tutorials',
        items: [
          {type: 'doc', id: 'tutorial1'},
          {type: 'doc', id: 'tutorial2'},
        ],
      },
    ];
  },
  numberPrefixParser(filename) {
    // Implement your own logic to extract a potential number prefix
    const numberPrefix = findNumberPrefix(filename);
    // Prefix found: return it with the cleaned filename
    if (numberPrefix) {
      return {
        numberPrefix,
        filename: filename.replace(prefix, ''),
      };
    }
    // No number prefix found
    return {numberPrefix: undefined, filename};
  },
  docLayoutComponent: '@theme/DocPage',
  docItemComponent: '@theme/DocItem',
  remarkPlugins: [require('remark-math')],
  rehypePlugins: [],
  beforeDefaultRemarkPlugins: [],
  beforeDefaultRehypePlugins: [],
  showLastUpdateAuthor: false,
  showLastUpdateTime: false,
  disableVersioning: false,
  includeCurrentVersion: true,
  lastVersion: undefined,
  versions: {
    current: {
      label: 'Android SDK v2.0.0 (WIP)',
      path: 'android-2.0.0',
      banner: 'none',
    },
    '1.0.0': {
      label: 'Android SDK v1.0.0',
      path: 'android-1.0.0',
      banner: 'unmaintained',
    },
  },
  onlyIncludeVersions: ['current', '1.0.0', '2.0.0'],
};
```

## Markdown front matter {#markdown-front-matter}

Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line `---` on either side.

Accepted fields:

<APITable>

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | file path (including folders, without the extension) | A unique document id. |
| `title` | `string` | Markdown title or `id` | The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. |
| `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. |
| `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
| `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
| `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
| `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. |
| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |
| `toc_min_heading_level` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
| `toc_max_heading_level` | `number` | `3` | The max heading level shown in the table of contents. Must be between 2 and 6. |
| `pagination_next` | <code>string \| null</code> | Next doc in the sidebar | The ID of the documentation you want the "Next" pagination to link to. Use `null` to disable showing "Next" for this page. |
| `pagination_prev` | <code>string \| null</code> | Previous doc in the sidebar | The ID of the documentation you want the "Previous" pagination to link to. Use `null` to disable showing "Previous" for this page. |
| `parse_number_prefixes` | `boolean` | `numberPrefixParser` plugin option | Whether number prefix parsing is disabled on this doc. See also [Using number prefixes](/docs/sidebar#using-number-prefixes). |
| `custom_edit_url` | `string` | Computed using the `editUrl` plugin option | The URL for editing this document. |
| `keywords` | `string[]` | `undefined` | Keywords meta tag for the document page, for search engines. |
| `description` | `string` | The first line of Markdown content | The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. |
| `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
| `slug` | `string` | File path | Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. |
| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. |

</APITable>

```ts
type Tag = string | {label: string; permalink: string};
```

Example:

```md
---
id: doc-markdown
title: Docs Markdown Features
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown
sidebar_position: 3
pagination_label: Markdown features
custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md
description: How do I find you when I cannot solve this problem
keywords:
  - docs
  - docusaurus
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
---

# Markdown Features

My Document Markdown content
```

## i18n {#i18n}

Read the [i18n introduction](../../i18n/i18n-introduction.md) first.

### Translation files location {#translation-files-location}

- **Base path**: `website/i18n/[locale]/docusaurus-plugin-content-docs`
- **Multi-instance path**: `website/i18n/[locale]/docusaurus-plugin-content-docs-[pluginId]`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]`

### Example file-system structure {#example-file-system-structure}

```bash
website/i18n/[locale]/docusaurus-plugin-content-docs
│
│ # translations for website/docs
├── current
│   ├── api
│   │   └── config.md
│   └── getting-started.md
├── current.json
│
│ # translations for website/versioned_docs/version-1.0.0
├── version-1.0.0
│   ├── api
│   │   └── config.md
│   └── getting-started.md
└── version-1.0.0.json
```