Aller au contenu principal
Version: 2.0.0-beta.3

📦 plugin-content-docs

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

Installation#

npm install --save @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 à travers des options de préréglage classiques au lieu de le faire comme ci-dessous.

Configuration#

docusaurus.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.         * Ceci n'inclura que la version "current" (le répertoire `/docs`)         */        disableVersioning: false,        /**         * Inclut la version "current" de vos docs (le répertoire `/docs`)         * Astuce : désactivez cette fonction si la version actuelle est un travail en cours, qui n'est pas prêt à être publié.         */        includeCurrentVersion: true,        /**         * 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 comme chemin path=/docs/myDoc).         * Remarque : il est possible de configurer le chemin et le libellé de la dernière version.         * Astuce : 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 les propriétés de chaque version de manière indépendante.         * - label : le libellé de la version         * - path : le chemin d'accès de la version         * - banner : la bannière à afficher en haut d'un document de cette version : "none" | "unreleased" | "unmaintained"         */        versions: {          /*          Exemple de 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',          },          */        },        /**         * 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 Frontmatter#

Les 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. Valeur par défaut : chemin du fichier (incluant les dossiers, sans l'extension)
  • title : Le texte du 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. Valeur par défaut : titre du Markdown ou id du doc
  • hide_title : S'il faut 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. Valeur par défaut : false
  • hide_table_of_content : S'il faut cacher la table des matières à droite. Valeur par défaut : false
  • sidebar_label : Le texte affiché dans la barre latérale du document pour ce document. Valeur par défaut : title
  • 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éments autogenerated de barre latérale. Peut être Int ou Float.
  • pagination_label : le texte utilisé dans les boutons suivant/précédent du document pour ce document. Valeur par défaut : sidebar_label, ou title
  • 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 plugin numberPrefixParser, et le nombre préfixé est utilisé comme sidebar_position. Utilisez parse_number_prefixes: false pour désactiver l'analyse des préfixes numériques sur ce doc. Valeur par défaut : parse_number_prefixes de l'option du plugin
  • custom_edit_url : L'URL pour modifer le document. Valeur par défaut : calculée en utilisant les options du plugin editUrl
  • keywords: Tag méta des mots clés pour la page du document, pour les moteurs de recherche
  • description : 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. Valeur par défaut : la première ligne du contenu Markdown
  • image : Image de couverture ou vignette qui sera utilisée lors de l'affichage du lien vers votre article.
  • slug : 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: Docs fonctionnalités Markdownhide_title: falsehide_table_of_contents: falsesidebar_label: Markdownsidebar_position: 3pagination_label: Fonctionnalités Markdowncustom_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ème ?keywords:  - docs  - docusaurusimage: https://i.imgur.com/mErPwqL.pngslug: /myDoc---# 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/<version>

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