📦 plugin-content-docs

Fournit la fonctionnalité Docs et c'est le plugin docs par défaut pour Docusaurus.

Installation

npm

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

Yarn

yarn add @docusaurus/plugin-content-docs

astuce

Si vous utilisez le preset @docusaurus/preset-classic, vous n'avez pas besoin d'installer ce plugin en tant que dépendance.

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. L'URL finale est calculée par 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é. Ignoré lorsque editUrl est une fonction.
editCurrentVersion	boolean	false	L'URL de modification ciblera toujours la version actuelle au lieu d'anciennes versions. Ignoré lorsque editUrl est une fonction.
routeBasePath	string	'docs'	Route URL pour la section des docs de votre site. NE PAS inclure un slash de fin. Utilisez / pour livrer des docs sans chemin de base.
tagsBasePath	string	'tags'	Route URL pour la page de la liste des tags de votre site. Il est préfixé par routeBasePath.
include	string[]	['**/*.{md,mdx}']	Tableau de patterns de glob correspondant aux fichiers Markdown à construire, relatif au chemin de contenu.
exclude	string[]	Voir l'exemple de configuration	Tableau de patterns de glob correspondant aux fichiers Markdown à exclure. Sert d'affinement basé sur l'option include.
sidebarPath	false | string	undefined	Chemin vers la configuration de la barre latérale. Utilisez false pour désactiver les barres latérales, ou undefined pour créer une barre latérale entièrement générée automatiquement.
sidebarCollapsible	boolean	true	Si les catégories de la barre latérale sont repliables par défaut. Consultez aussi Catégories repliables
sidebarCollapsed	boolean	true	Si les catégories de la barre latérale sont réduites par défaut. Consultez aussi Catégories développées par défaut
sidebarItemsGenerator	SidebarGenerator	Omis	Fonction utilisée pour remplacer les éléments de type 'autogenerated' avec de vrais éléments de la barre latérale (docs, catégories, liens. .). Consultez aussi Personnalisez le générateur d'éléments de la barre latérale
numberPrefixParser	boolean | PrefixParser	Omis	Logique d'analyse personnalisée pour extraire les préfixes numériques des noms de fichiers. Utilisez false pour désactiver ce comportement et laisser la documentation intacte et true pour utiliser l'analyseur par défaut. Consultez aussi Utilisez les préfixes de nombre
docLayoutComponent	string	'@theme/DocPage'	Composant racine de mise en page de chaque page de doc. Fournit le contexte des données de version, et n'est pas démonté lors du changement de documentation.
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. Une erreur se produira si includeCurrentVersion: false et disableVersioning: true.
includeCurrentVersion	boolean	true	Inclue la version « courante » de vos docs.
lastVersion	string	Première version dans 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: {
  /** L'élément de la barre latérale avec le type "autogenerated" à transformer. */
  item: {type: 'autogenerated'; dirName: string};
  /** Métadonnées utiles pour la version à laquelle appartient cette barre latérale. */
  version: {contentPath: string; versionName: string};
  /** Tous les docs de cette version (non filtré). */
  docs: {
    id: string;
    title: string;
    frontMatter: DocFrontMatter & Record<string, unknown>;
    source: string;
    sourceDirName: string;
    sidebarPosition?: number | undefined;
  }[];
  /** Analyseur de nombres configuré pour ce plugin. */
  numberPrefixParser: PrefixParser;
  /** L'indexeur de catégorie par défaut que vous pouvez remplacer. */
  isCategoryIndex: CategoryIndexMatcher;
  /**
   * la clé est le chemin relatif au répertoire de contenu du doc, la valeur est
   * le contenu du fichier de métadonnées de la catégorie.
   */
  categoriesMetadata: {[filePath: string]: CategoryMetadata};
  /**
   * Utile pour réutiliser/améliorer la logique de génération de la barre latérale par défaut à partir de
   * Docusaurus.
   */
  defaultSidebarItemsGenerator: SidebarGenerator;
  // Renvoie un tableau d'éléments de la barre latérale — identique à ce que vous pouvez déclarer dans
  //  sidebars.js, sauf pour les raccourcis. Voir https://docusaurus. o/docs/sidebar/items
}) => Promise<SidebarItem[]>;

type CategoryIndexMatcher = (param: {
  /** Le nom du fichier, sans extension */
  fileName: string;
  /**
   * La liste des répertoires, du niveau le plus bas au plus élevé.
   * S'il n'y a pas de nom de répertoire, les répertoires sont ['.']
   */
  directories: string[];
  /** L'extension, avec un point au début */
  extension: string;
}) => boolean;

VersionsConfig

type VersionsConfig = {
  [versionName: string]: {
    /**
     * Le chemin de base de la version, sera ajouté à `baseUrl` +
     * `routeBasePath`.
     */
    path?: string;
    /** Le libellé de la version à utiliser dans les badges, les listes déroulantes, etc. */
    label?: string;
    /** La bannière à afficher en haut d'un doc de cette version. */
    banner?: 'none' | 'unreleased' | 'unmaintained';
    /** Affiche un badge avec le libellé de la version en haut de chaque doc. */
    badge?: boolean;
    /** Ajoute un nom de classe personnalisé à l'élément <html> de chaque doc */
    className?: string;
  };
};

Exemple de 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.

Options du preset

Si vous utilisez un preset, configurez ce plugin via le options du preset :

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs',
          breadcrumbs: true,
          // Cas simple : string editUrl
          // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
          // Cas avancé : 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,
          }) {
            // Utilise les données fournies pour générer une section de la barre latérale personnalisée
            return [
              {type: 'doc', id: 'intro'},
              {
                type: 'category',
                label: 'Tutorials',
                items: [
                  {type: 'doc', id: 'tutorial1'},
                  {type: 'doc', id: 'tutorial2'},
                ],
              },
            ];
          },
          numberPrefixParser(filename) {
            // Implémentez votre propre logique pour extraire un préfixe de nombre éventuel
            const numberPrefix = findNumberPrefix(filename);
            // Préfixe trouvé : retourne le fichier avec le nom du fichier nettoyé
            if (numberPrefix) {
              return {
                numberPrefix,
                filename: filename.replace(prefix, ''),
              };
            }
            // Aucun préfixe de numéro trouvé
            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'],
        },
      },
    ],
  ],
};

Options du plugin

Si vous utilisez un plugin autonome, fournissez des options directement au plugin :

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        path: 'docs',
        breadcrumbs: true,
        // Cas simple : string editUrl
        // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
        // Cas avancé : 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,
        }) {
          // Utilise les données fournies pour générer une section de la barre latérale personnalisée
          return [
            {type: 'doc', id: 'intro'},
            {
              type: 'category',
              label: 'Tutorials',
              items: [
                {type: 'doc', id: 'tutorial1'},
                {type: 'doc', id: 'tutorial2'},
              ],
            },
          ];
        },
        numberPrefixParser(filename) {
          // Implémentez votre propre logique pour extraire un préfixe de nombre éventuel
          const numberPrefix = findNumberPrefix(filename);
          // Préfixe trouvé : retourne le fichier avec le nom du fichier nettoyé
          if (numberPrefix) {
            return {
              numberPrefix,
              filename: filename.replace(prefix, ''),
            };
          }
          // Aucun préfixe de numéro trouvé
          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 frontmatter

Les documents Markdown peuvent utiliser les champs de métadonnées Markdown du frontmatter suivants, entourés par une ligne --- de chaque côté.

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	Titre Markdown ou 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 ou 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	Contrôle la position d'un doc à l'intérieur de la barre latérale générée lorsque vous utilisez les éléments autogenerated de la barre latérale. Consultez aussi Métadonnées de la barre latérale générées automatiquement.
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	string	undefined	Attribuez des métadonnées personnalisées à l'élément de la barre latérale faisant référence à ce doc.
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. Utilisez null pour désactiver l'affichage "Suivant" pour cette 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. Utilisez null pour désactiver l'affichage "Précédent" pour cette page.
parse_number_prefixes	boolean	option numberPrefixParser du plugin	Si l'analyse des préfixes numériques est désactivée sur ce doc. Consultez aussi Utilisez les préfixes de nombre.
custom_edit_url	string	Calculé à l'aide de l'option editUrl du plugin	L'URL pour modifier ce document.
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	La description de votre document, qui deviendra la <meta name="description" content="..."/> et <meta property="og:description" content="..."/> dans <head>, utilisé par les moteurs de recherche.
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	Permet de personnaliser l'URL du document (/<routeBasePath>/<slug>). Prise en charge de multiples formats : slug: my-doc, slug: /my/path/myDoc, slug: /.
tags	Tag[]	undefined	Une liste de chaînes ou d'objets de deux champs de chaîne label et permalink pour taguer vos docs.
draft	boolean	false	Un booléen pour indiquer qu'un document est en cours de rédaction. Les brouillons de document seront affichés uniquement lors du développement.
last_update	FileChange	undefined	Permet de remplacer l'auteur et/ou la date de la dernière mise à jour. La date peut être toute chaîne de date interprétable.

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

Lisez l’introduction i18n en premier.

Emplacement des fichiers de traduction

• Chemin de base : website/i18n/[locale]/docusaurus-plugin-content-docs
• Chemin d'accès multi-instance : website/i18n/[locale]/docusaurus-plugin-content-docs-[pluginId]
• Fichiers JSON : extrait avec docusaurus write-translations
• Fichiers Markdown : website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]

Exemple de structure du système de fichiers

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