Version: 2.0.0-beta.6

📦 plugin-content-docs

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

Installation#

npm
Yarn

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

yarn 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 data on filesystem relative to site dir.
`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.
`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`	`false \| string`	`undefined` (creates autogenerated sidebar)	Path to sidebar configuration.
`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'` by 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
`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.
`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). 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. Note: the path and label of the last version are configurable. 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. Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews.

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#

Here's an example configuration object.

You can provide it as preset options or plugin options.

tip

Most Docusaurus users configure this plugin through the preset options.

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',  sidebarItemsGenerator: async function ({    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: function (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'],};

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',          // ... configuration object here        },      },    ],  ],};

Plugin options#

If you are using a standalone plugin, provide options directly to the plugin:

docusaurus.config.js

module.exports = {  plugins: [    [      '@docusaurus/plugin-content-docs',      {        path: 'docs',        // ... configuration object here      },    ],  ],};

Markdown Frontmatter#

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

Accepted fields:

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 metadatas.
`hide_title`	`boolean`	`false`	Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, 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.
`parse_number_prefixes`	`boolean`	`numberPrefixParser` plugin option	Whether number prefix parsing is disabled on this doc. See also 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.

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

Example:

---id: doc-markdowntitle: Docs Markdown Featureshide_title: falsehide_table_of_contents: falsesidebar_label: Markdownsidebar_position: 3pagination_label: Markdown featurescustom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.mddescription: How do I find you when I cannot solve this problemkeywords:  - docs  - docusaurusimage: https://i.imgur.com/mErPwqL.pngslug: /myDoc---# Markdown Features
My Document Markdown content

i18n#

Read the i18n introduction first.

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
Markdown files: website/i18n/<locale>/docusaurus-plugin-content-docs/<version>

Example file-system structure#

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