📦 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

pnpm

pnpm add @docusaurus/plugin-content-docs

Bun

bun 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	Path to a sidebars configuration file, loaded in a Node.js context. 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 Personnalisation du 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
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/DocRoot'	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.
recmaPlugins	any[]	[]	Recma plugins passed to 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	Only for Markdown pages. Affichage ou non de la dernière date de mise à jour du doc. Cela nécessite l'accès à l'historique git pendant la construction, et ne fonctionnera donc pas correctement avec des clones superficiels (un défaut courant pour les systèmes de CI). With GitHub actions/checkout, use fetch-depth: 0. When deploying to Vercel, set the environment variable VERCEL_DEEP_CLONE=true.
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.
tags	string | false | null | undefined	tags.yml	Path to a YAML file listing pre-defined tags. Relative to the docs version content directories.
onInlineTags	'ignore' | 'log' | 'warn' | 'throw'	warn	The plugin behavior when docs contain inline tags (not appearing in the list of pre-defined tags, usually docs/tags.yml).

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'