Version: 3.0.0-rc.1

📦 plugin-content-docs

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

Installation

npm
Yarn
pnpm

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

yarn add @docusaurus/plugin-content-docs

pnpm add @docusaurus/plugin-content-docs

astuce

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

Vous pouvez configurer ce plugin via les options du preset.

Configuration

Champs acceptés :

Nom	Type	Par défaut	Description
`path`	`string`	`'docs'`	Chemin vers le répertoire de contenu des docs sur le système de fichiers, relatif au répertoire du site.
`editUrl`	`string \| EditUrlFunction`	`undefined`	URL de base pour modifier votre site. The final URL is computed by `editUrl + relativeDocPath`. L'utilisation d'une fonction permet un contrôle plus nuancé pour chaque fichier. Omettre cette variable désactivera entièrement les liens de modification.
`editLocalizedFiles`	`boolean`	`false`	L'URL de modification ciblera le fichier localisé, au lieu du fichier original non localisé. Ignored when `editUrl` is a function.
`editCurrentVersion`	`boolean`	`false`	L'URL de modification ciblera toujours la version actuelle au lieu d'anciennes versions. Ignored when `editUrl` is a function.
`routeBasePath`	`string`	`'docs'`	Route URL pour la section des docs de votre site. DO NOT include a trailing slash. Use `/` for shipping docs without base path.
`tagsBasePath`	`string`	`'tags'`	Route URL pour la page de la liste des tags de votre site. It is prepended to the `routeBasePath`.
`include`	`string[]`	`['*/.{md,mdx}']`	Tableau de patterns de glob correspondant aux fichiers Markdown à construire, relatif au chemin de contenu.
`exclude`	`string[]`	See example configuration	Tableau de patterns de glob correspondant aux fichiers Markdown à exclure. Serves as refinement based on the `include` option.
`sidebarPath`	`false \| string`	`undefined`	Chemin vers la configuration de la barre latérale. Use `false` to disable sidebars, or `undefined` to create a fully autogenerated sidebar.
`sidebarCollapsible`	`boolean`	`true`	Si les catégories de la barre latérale sont repliables par défaut. See also Collapsible categories
`sidebarCollapsed`	`boolean`	`true`	Si les catégories de la barre latérale sont réduites par défaut. 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	Logique d'analyse personnalisée pour extraire les préfixes numériques des noms de fichiers. 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'`	Composant parent de toutes les pages du plugin docs (incluant les versions). Il reste monté lors de la navigation entre les pages de la documentation et les versions.
`docVersionRootComponent`	`string`	`'@theme/DocVersionLayout'`	Composant parent de toutes les pages de docs d'une version individuelle (pages de docs avec barres latérales, pages de tags). Il reste monté lors de la navigation entre les pages de cette version spécifique.
`docRootComponent`	`string`	`'@theme/DocPage'`	Composant parent de toutes les pages de documents avec des barres latérales (pages de documents ordinaires, pages d'index générées par des catégories). Il reste monté lors de la navigation entre ces pages.
`docItemComponent`	`string`	`'@theme/DocItem'`	Conteneur principal du document, avec table des matières, pagination, etc.
`docTagsListComponent`	`string`	`'@theme/DocTagsListPage'`	Composant racine de la page de la liste des tags
`docTagDocListComponent`	`string`	`'@theme/DocTagDocListPage'`	Composant racine de la page « des docs contenant le tag X ».
`docCategoryGeneratedIndexComponent`	`string`	`'@theme/DocCategoryGeneratedIndexPage'`	Composant racine de la page d'index des catégories générées.
`remarkPlugins`	`any[]`	`[]`	Plugins Remark passés à MDX.
`rehypePlugins`	`any[]`	`[]`	Plugins Rehype passés à MDX.
`beforeDefaultRemarkPlugins`	`any[]`	`[]`	Les plugins Remark personnalisés sont transmis à MDX avant les plugins Remark par défaut de Docusaurus.
`beforeDefaultRehypePlugins`	`any[]`	`[]`	Les plugins Rehype personnalisés sont transmis à MDX avant les plugins Rehype par défaut de Docusaurus.
`showLastUpdateAuthor`	`boolean`	`false`	Affichage ou non de l'auteur de la dernière mise à jour du doc.
`showLastUpdateTime`	`boolean`	`false`	Affichage ou non de la dernière date de mise à jour du doc.
`breadcrumbs`	`boolean`	`true`	Active ou désactive le fil d'Ariane sur les pages de docs.
`disableVersioning`	`boolean`	`false`	Désactive explicitement le versionnage même lorsque plusieurs versions existent. Ainsi, le site n'inclura que la version actuelle. Will error if `includeCurrentVersion: false` and `disableVersioning: true`.
`includeCurrentVersion`	`boolean`	`true`	Inclue la version « courante » de vos docs.
`lastVersion`	`string`	First version in `versions.json`	La version vers laquelle on navigue en priorité et qui est affichée par défaut pour les éléments de la barre de navigation des docs.
`onlyIncludeVersions`	`string[]`	Toutes les versions disponibles	Inclut uniquement un sous-ensemble de toutes les versions disponibles.
`versions`	`VersionsConfig`	`{}`	Personnalisation indépendante des propriétés de chaque version.

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

Vous pouvez configurer ce plugin via les options du preset ou du plugin.

astuce

La plupart des utilisateurs de Docusaurus configurent ce plugin via les options du preset.

Preset options
Plugin 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'},
                  {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('./my-remark-plugin')],
          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'],
        },
      },
    ],
  ],
};

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',
        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'},
                {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('./my-remark-plugin')],
        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 documents can use the following Markdown front matter metadata fields, enclosed by a line --- on either side.

Champs acceptés :

Nom	Type	Par défaut	Description
`id`	`string`	le chemin du fichier (y compris les dossiers, sans l'extension)	Un ID unique du doc.
`title`	`string`	Markdown title or `id`	Le titre de votre document. Utilisé pour les métadonnées de la page et comme valeur de secours à plusieurs endroits (barre latérale, boutons suivant/précédent...). Ajouté automatiquement en haut de votre document s'il ne contient pas de titre Markdown.
`pagination_label`	`string`	`sidebar_label` or `title`	Le texte utilisé dans le document pour les boutons suivant/précédent pour ce document.
`sidebar_label`	`string`	`title`	Le texte affiché dans la barre latérale du document pour ce document.
`sidebar_position`	`number`	Ordre par défaut	Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also Autogenerated sidebar metadata.
`sidebar_class_name`	`string`	`undefined`	Donne à la barre latérale correspondante un nom de classe spécial lorsque vous utilisez les barres latérales générées automatiquement.
`sidebar_custom_props`	`object`	`undefined`	Assign custom props to the sidebar item referencing this doc
`displayed_sidebar`	`string`	`undefined`	Forcer l'affichage d'une barre latérale donnée lors de la navigation dans le document courant. Read the multiple sidebars guide for details.
`hide_title`	`boolean`	`false`	Si vous voulez cacher le titre en haut du doc. Il ne masque qu'un titre déclaré par le biais du frontmatter, et n'a aucun effet sur un titre Markdown en haut de votre document.
`hide_table_of_contents`	`boolean`	`false`	S'il faut cacher la table des matières à droite.
`toc_min_heading_level`	`number`	`2`	Le niveau de titre minimum affiché dans la table des matières. Doit être compris entre 2 et 6 et inférieur ou égal à la valeur maximale.
`toc_max_heading_level`	`number`	`3`	Le niveau de titre maximum affiché dans la table des matières. Doit être compris entre 2 et 6.
`pagination_next`	`string \| null`	Le doc suivant dans la barre latérale	L'ID de la documentation à laquelle vous voulez que la pagination "Suivant" soit liée. Use `null` to disable showing "Next" for this page.
`pagination_prev`	`string \| null`	Le doc précédent dans la barre latérale	L'ID de la documentation à laquelle vous voulez que la pagination "Précédent" soit liée. Use `null` to disable showing "Previous" for this page.
`parse_number_prefixes`	`boolean`	`numberPrefixParser` plugin option	Si l'analyse des préfixes numériques est désactivée sur ce doc. See also Using number prefixes.
`custom_edit_url`	`string \| null`	Computed using the `editUrl` plugin option	L'URL pour modifier ce document. Use `null` to disable showing "Edit this page" for this page.
`keywords`	`string[]`	`undefined`	Balise meta de mots clés pour la page du document, pour les moteurs de recherche.
`description`	`string`	La première ligne du contenu Markdown	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`	Couverture ou image miniature qui sera utilisée lors de l'affichage du lien vers votre article.
`slug`	`string`	Chemin du fichier	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.
`draft`	`boolean`	`false`	Les brouillons de document seront disponibles uniquement lors du développement.
`unlisted`	`boolean`	`false`	Les documents non listés seront disponibles à la fois en développement et en production. Ils seront « cachés » en production, non indexés, exclus des sitemaps, et ne peuvent être consultés que par les utilisateurs ayant un lien direct.
`last_update`	`FileChange`	`undefined`	Permet de remplacer l'auteur et/ou la date de la dernière mise à jour. Date can be any parsable date string.

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

type FileChange = {date: string; author: string};

Exemple :

---
id: doc-markdown
title: Docs fonctionnalités Markdown
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown
sidebar_position: 3
pagination_label: Fonctionnalités Markdown
custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md
description: Comment vous trouver lorsque je ne peux pas résoudre ce problème ?
keywords:
  - docs
  - docusaurus
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
last_update:
  date: 1/1/2000
  author: nom auteur personnalisé
---

# Fonctionnalités Markdown

Contenu de mon document en format Markdown

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/[versionName]

Example file-system structure

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

📦 plugin-content-docs

Installation​

Configuration​

Types​

EditUrlFunction​

PrefixParser​

SidebarGenerator​

VersionsConfig​

Example configuration​

Markdown front matter​

i18n​

Translation files location​

Example file-system structure​