Skip to main content
Version: 2.0.0-beta.4

📦 plugin-content-docs

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

Installation#

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

If you have installed @docusaurus/preset-classic, you don't need to install it as a dependency. You can also configure it through the classic preset options instead of doing it like below.

Configuration#

docusaurus.config.js
module.exports = {  plugins: [    [      '@docusaurus/plugin-content-docs',      {        /**         * Path to data on filesystem relative to site dir.         */        path: 'docs',        /**         * Base url to edit your site.         * Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"         * Omitting this variable entirely will disable edit links.         */        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',        /**         * For advanced cases, compute the edit url for each Markdown file yourself.         */        editUrl: function ({          locale,          version,          versionDocsDirPath,          docPath,          permalink,        }) {          return `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`;        },        /**         * Useful if you commit localized files to git.         * When Markdown files are localized, the edit url will target the localized file,         * instead of the original unlocalized file.         * Note: this option is ignored when editUrl is a function         */        editLocalizedFiles: false,        /**         * Useful if you don't want users to submit doc pull-requests to older versions.         * When docs are versioned, the edit url will link to the doc         * in current version, instead of the versioned doc.         * Note: this option is ignored when editUrl is a function         */        editCurrentVersion: false,        /**         * URL route for the docs section of your site.         * *DO NOT* include a trailing slash.         * INFO: It is possible to set just `/` for shipping docs without base path.         */        routeBasePath: 'docs',        include: ['**/*.md', '**/*.mdx'], // Extensions to include.        /**         * No route will be created for matching files         */        exclude: [          '**/_*.{js,jsx,ts,tsx,md,mdx}',          '**/_*/**',          '**/*.test.{js,jsx,ts,tsx}',          '**/__tests__/**',        ],        /**         * Path to sidebar configuration for showing a list of markdown pages.         */        sidebarPath: 'sidebars.js',        /**         * By default, all sidebar categories will be collapsible.         * This can be overriden per-category.         */        sidebarCollapsible: true,        /**         * By default, all sidebar categories will be initialized in a collapsed state.         * This can be overriden per-category.         */        sidebarCollapsed: false,        /**         * Function used to replace the sidebar items of type "autogenerated"         * by real sidebar items (docs, categories, links...)         */        sidebarItemsGenerator: async function ({          defaultSidebarItemsGenerator, // useful to re-use/enhance default sidebar generation logic from Docusaurus          numberPrefixParser, // numberPrefixParser configured for this plugin          item, // the sidebar item with type "autogenerated"          version, // the current version          docs, // all the docs of that version (unfiltered)        }) {          // 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'},              ],            },          ];        },        /**         * The Docs plugin supports number prefixes like "01-My Folder/02.My Doc.md".         * Number prefixes are extracted and used as position to order autogenerated sidebar items.         * For conveniency, number prefixes are automatically removed from the default doc id, name, title.         * This parsing logic is configurable to allow all possible usecases and filename patterns.         * Use "false" to disable this behavior and leave the docs untouched.         */        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};        },        /**         * Theme components used by the docs pages         */        docLayoutComponent: '@theme/DocPage',        docItemComponent: '@theme/DocItem',        /**         * Remark and Rehype plugins passed to MDX         */        remarkPlugins: [          /* require('remark-math') */        ],        rehypePlugins: [],        /**         * Custom Remark and Rehype plugins passed to MDX before         * the default Docusaurus Remark and Rehype plugins.         */        beforeDefaultRemarkPlugins: [],        beforeDefaultRehypePlugins: [],        /**         * Whether to display the author who last updated the doc.         */        showLastUpdateAuthor: false,        /**         * Whether to display the last date the doc was updated.         */        showLastUpdateTime: false,        /**         * By default, versioning is enabled on versioned sites.         * This is a way to explicitly disable the versioning feature.         * This will only include the "current" version (the `/docs` directory)         */        disableVersioning: false,        /**         * 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         */        includeCurrentVersion: true,        /**         * The last version is the one we navigate to in priority on versioned sites         * It is the one displayed by default in docs navbar items         * By default, the last version is the first one to appear in versions.json         * By default, the last version is at the "root" (docs have path=/docs/myDoc)         * Note: it is possible to configure the path and label of the last version         * Tip: using lastVersion: 'current' make sense in many cases         */        lastVersion: undefined,        /**         * The docusaurus versioning defaults don't make sense for all projects         * This gives the ability customize the properties of each version independantly         * - label: the label of the version         * - path: the route path of the version         * - banner: the banner to show at the top of a doc of that version: "none" | "unreleased" | "unmaintained"         */        versions: {          /*          Example configuration:          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',          },          */        },        /**         * Sometimes you only want to 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         */        onlyIncludeVersions: undefined, // ex: ["current", "1.0.0", "2.0.0"]      },    ],  ],};

Markdown Frontmatter#

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

  • id: A unique document id. Default value: file path (including folders, without the extension)
  • title: 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. Default value: Markdown title or doc id
  • hide_title: 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. Default value: false
  • hide_table_of_contents: Whether to hide the table of contents to the right. Default value: false
  • sidebar_label: The text shown in the document sidebar for this document. Default value: title
  • sidebar_position: Permits to control the position of a doc inside the generated sidebar slice, when using autogenerated sidebar items. Can be Int or Float.
  • pagination_label: The text used in the document next/previous buttons for this document. Default value: sidebar_label, or title
  • parse_number_prefixes: When a document has a number prefix (001 - My Doc.md, 2. MyDoc.md...), it is automatically parsed and extracted by the plugin numberPrefixParser, and the number prefix is used as sidebar_position. Use parse_number_prefixes: false to disable number prefix parsing on this doc. Default value: parse_number_prefixes plugin option
  • custom_edit_url: The URL for editing this document. Default value: computed using the editUrl plugin options
  • keywords: Keywords meta tag for the document page, for search engines
  • description: 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. Default value: the first line of Markdown content
  • image: Cover or thumbnail image that will be used when displaying the link to your post.
  • slug: Allows to customize the document url (/<routeBasePath>/<slug>). Support multiple patterns: slug: my-doc, slug: /my/path/myDoc, slug: /.

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