Aller au contenu principal
Version: 2.0.0-beta.0

📦 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 via les options du preset classic 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.         */        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 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. 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, le title du document sera par défaut celui de son id
  • hide_title : S'il faut cacher le titre en haut du doc. Par défaut, c'est false
  • hide_table_of_content : S'il faut cacher la table des matières à droite. Par défaut, c'est false
  • 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, le sidebar_label du document sera par défaut celui de son 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.
  • 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 de nombre sur ce doc
  • custom_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 vers editUrl à 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 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. Si ce champ n'est pas présent, il reprendra par défaut la première ligne du contenu
  • 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: 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

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