Version: 2.0.0-alpha.72

📦 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

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.
         * Attention : cela changera
         */
        sidebarPath: '',
        /**
         * Composants du thème utilisés par les pages de 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 Remark et Rehype par défaut de Docusaurus.
         */
        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
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

Exemple :

---
id: doc-markdown
title: Markdown Features
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown :)
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/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
---
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