📦 plugin-content-docs
Fournit la fonctionnalité Docs et c'est le plugin docs par défaut pour Docusaurus.
#
Installation- npm
- Yarn
npm install --save @docusaurus/plugin-content-docs
yarn add @docusaurus/plugin-content-docs
astuce
Si vous avez installé @docusaurus/preset-classic
, vous n'avez pas besoin de l'installer en tant que dépendance. Vous pouvez également le configurer via les options du preset classic au lieu de le faire comme ci-dessous.
#
Configurationdocusaurus.config.js
module.exports = { plugins: [ [ '@docusaurus/plugin-content-docs', { /** * Chemin vers les données sur le système de fichiers par rapport au répertoire du site. */ path: 'docs', /** * URL de base pour modifier votre site. * Docusaurus calculera le editUrl final avec "editUrl + relativeDocPath". */ editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/', /** * Pour les cas particuliers, calculez vous-même l'url d'édition pour chaque fichier markdown. */ editUrl: function ({ locale, version, versionDocsDirPath, docPath, permalink, }) { return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`; }, /** * Utile si vous livrez des fichiers localisés sur git. * Lorsque les fichiers markdown sont localisés, l'URL d'édition ciblera le fichier localisé, * au lieu du fichier original non localisé. * Remarque : cette option est ignorée lorsque editUrl est une fonction */ editLocalizedFiles: false, /** * Utile si vous ne voulez pas que les utilisateurs soumettent des pull-requests aux anciennes versions. * Lorsque les docs sont versionnés, l'url de modification sera liée au doc * dans la version actuelle, au lieu de la doc versionnée. * Remarque : cette option est ignorée lorsque editUrl est une fonction */ editCurrentVersion: false, /** * Route URL pour la section docs de votre site. * * * NE PAS inclure de slash. * INFO : Il est possible de mettre juste `/` pour les docs envoyées sans chemin de base. */ routeBasePath: 'docs', include: ['**/*.md', '**/*.mdx'], // Extensions à inclure. /** * Chemin vers la configuration de la barre latérale pour afficher une liste des pages de markdown. */ sidebarPath: 'sidebars.js', /** * Fonction utilisée pour remplacer les éléments de la barre latérale de type "autogenerated". * par des éléments réels de la barre latérale (docs, catégories, liens...) */ sidebarItemsGenerator: async function ({ defaultSidebarItemsGenerator, // utile pour réutiliser/améliorer la logique de génération de barre latérale par défaut à partir de Docusaurus numberPrefixParser, // numberPrefixParser configuration pour ce plugin item, // l'élément de la barre latérale de type "autogenerated" version, // la version actuelle docs, // tous les docs de cette version (non filtrées) }) { // Utilise les données fournies pour générer une barre latérale personnalisée return [ {type: 'doc', id: 'intro'}, { type: 'category', label: 'Tutorials', items: [ {type: 'doc', id: 'tutorial1'}, {type: 'doc', id: 'tutorial2'}, ], }, ]; }, /** * Le plugin Docs prend en charge les préfixes de nombre comme "01-My Folder/02.My Doc.md". * Les préfixes de nombres sont extraits et utilisés comme position pour ordonner les éléments générés automatiquement dans la barre latérale. * Pour des raisons de commodité, les préfixes numériques sont par défaut automatiquement supprimés des doc id, name, title. * Cette logique d'analyse est configurable pour permettre tous les cas d'utilisation possibles et les patterns de noms de fichiers. * Utilisez "false" pour désactiver ce comportement et laisser la documentation intacte. */ numberPrefixParser: function (filename) { // Implémentez votre propre logique pour extraire un préfixe de numéro éventuel const numberPrefix = findNumberPrefix(filename); // Préfixe trouvé : le retourner avec le nom du fichier nettoyé if (numberPrefix) { return { numberPrefix, filename: filename.replace(prefix, ''), }; } // Aucun préfixe de nombre trouvé return {numberPrefix: undefined, filename}; }, /** * Composants de thème utilisés par les pages docs */ docLayoutComponent: '@theme/DocPage', docItemComponent: '@theme/DocItem', /** * Les plugins Remark et Rehype passés à MDX */ remarkPlugins: [ /* require('remark-math') */ ], rehypePlugins: [], /** * Les plugins Remark et Rehype personnalisés sont passés à MDX avant * les plugins Docusaurus Remark et Rehype par défaut. */ beforeDefaultRemarkPlugins: [], beforeDefaultRehypePlugins: [], /** * S'il faut afficher l'auteur qui a mis à jour la doc. */ showLastUpdateAuthor: false, /** * Si la dernière date de mise à jour de la documentation doit être affichée. */ showLastUpdateTime: false, /** * Par défaut, la gestion de version est activé sur les sites versionnés. * C'est une façon de désactiver explicitement la fonctionnalité de version. */ disableVersioning: false, /** * Ignore la prochaine version lorsque la gestion de version est activée. * Cela ne générera pas de fichiers HTML dans la compilation pour les documents * dans le répertoire `/docs/next`, seulement les docs versionnées. */ excludeNextVersionDocs: false, /** * La dernière version est celle vers laquelle on navigue en priorité sur les sites versionnés. * C'est celle qui est affichée par défaut dans les éléments de la barre de navigation de la docs * Par défaut, la dernière version est la première à apparaître dans versions.json. * Par défaut, la dernière version est à la "racine" (docs a le chemin=/docs/myDoc). * Remarque : il est possible de configurer le chemin et le libellé de la dernière version. * Conseil pour l'utilisation de lastVersion : 'current' est utile dans de nombreux cas. */ lastVersion: undefined, /** * Les versions par défaut de docusaurus n'ont pas de sens pour tous les projets. * Ceci donne la possibilité de personnaliser le libellé et le chemin de chaque version. * Vous pouvez ne pas aimer cette version par défaut */ versions: { /* Exemple de configuration : current: { label: 'Android SDK v2.0.0 (WIP)', path: 'android-2.0.0', }, '1.0.0': { label: 'Android SDK v1.0.0', path: 'android-1.0.0', }, */ }, /** * Parfois, vous ne souhaitez inclure qu'un sous-ensemble de toutes les versions disponibles. * Astuce : limitez à 2 ou 3 versions pour améliorer le temps de démarrage et de construction en dev et déployer les aperçus */ onlyIncludeVersions: undefined, // ex: ["current", "1.0.0", "2.0.0"] }, ], ],};
#
Markdown FrontmatterLes documents Markdown peuvent utiliser les champs de métadonnées markdown frontmatter suivants, entourés par une ligne ---
de chaque côté :
id
 : Un id de document unique. Si ce champ n'est pas présent, l'id
du document par défaut est son nom de fichier (sans l'extension)title
 : Le titre de votre document. Si ce champ n'est pas présent, letitle
du document sera par défaut celui de sonid
hide_title
 : S'il faut cacher le titre en haut du doc. Par défaut, c'estfalse
hide_table_of_content
 : S'il faut cacher la table des matières à droite. Par défaut, c'estfalse
sidebar_label
 : Le texte affiché dans la barre latérale du document et dans le bouton suivant/précédent pour ce document. Si ce champ n'est pas présent, lesidebar_label
du document sera par défaut celui de sontitle
sidebar_position
: Permet de contrôler la position d'un doc à l'intérieur de la barre latérale générée, lors de l'utilisation d'élémentsautogenerated
de barre latérale. Peut être Int ou Float.parse_number_prefixes
 : Quand un document a un nombre comme préfixe (001 - Mon Doc.md
,2. MyDoc.md
...), il est automatiquement analysé et extrait par le pluginnumberPrefixParser
, et le nombre préfixé est utilisé commesidebar_position
. Utilisezparse_number_prefixes: false
pour désactiver l'analyse de nombre sur ce doccustom_edit_url
 : L'URL pour modifer le document. Si ce champ n'est pas présent, l'URL de modification du document sera renvoyée verseditUrl
à partir des champs d'options passés Ãdocusaurus-plugin-content-docs
keywords
: Tag méta des mots clés pour la page du document, pour les moteurs de recherchedescription
: La description de votre document qui sera fournit dans<meta name="description" content="..."/>
et<meta property="og:description" content="..."/>
du<head>
, utilisé par les moteurs de recherche. Si ce champ n'est pas présent, il reprendra par défaut la première ligne du contenuimage
 : Image de couverture ou vignette qui sera utilisée lors de l'affichage du lien vers votre articleslug
 : Permet de personnaliser l'url du document (<routeBasePath><slug>
). Prise en charge de multiples formats :slug: mon-doc
,slug: /mon/chemin/monDoc
,slug: /
Exemple :
---id: doc-markdowntitle: Markdown Featureshide_title: falsehide_table_of_contents: falsesidebar_label: Markdown :)custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.mddescription: Comment vous trouver lorsque je ne peux pas résoudre ce problèmekeywords: - docs - docusaurusimage: https://i.imgur.com/mErPwqL.pngslug: /myDoc---Contenu de mon document au format Markdown
#
i18nLisez 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/<version>
#
Exemple de structure du système de fichierswebsite/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