Version: 2.0.0-beta.6 🚧

📦 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 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 les données sur le système de fichier par rapport au répertoire du site.
`editUrl`	!!crwdBlockTags_235_sgaTkcolBdwrc!!	`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.
`include`	`string[]`	`['*/.{md,mdx}']`	Les fichiers correspondants seront inclus et traités.
`exclude`	`string[]`	Voir l'exemple de configuration	Aucune route ne sera créée pour les fichiers correspondants.
`sidebarPath`	!!crwdBlockTags_236_sgaTkcolBdwrc!!	`undefined` (crée la barre latérale générée automatiquement)	Chemin vers la configuration de la barre latérale.
`sidebarCollapsible`	`boolean`	`true`	Si les catégories de la barre latérale sont réduites 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'` par de vrais éléments de la barre latérale (docs, catégories, liens. .). Consultez aussi Personnalisez le générateur d'éléments de la barre latérale
`numberPrefixParser`	!!crwdBlockTags_237_sgaTkcolBdwrc!!	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
`docLayoutComponent`	`string`	`'@theme/DocPage'`	Composant racine de mise en page de chaque page de doc.
`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 ».
`remarkPlugins`	`any[]`	`[]`	Plugins Remark passés à MDX.
`rehypePlugins`	`any[]`	`[]`	Plugins Rehype passés à 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`	Affichage ou non de la dernière date de mise à jour du doc.
`disableVersioning`	`boolean`	`false`	Désactiver explicitement la fonction de versionnage même avec des versions. Cela n'inclura que la version « courante » (le répertoire `/docs`).
`includeCurrentVersion`	`boolean`	`true`	Inclue la version « courante » de vos docs (le répertoire `/docs`). Conseil : désactivez cette fonction si la version actuelle est en cours, non prête à être publiée.
`lastVersion`	`string`	`current` (alias pour la première version à apparaître dans `versions.json` et à la « racine » (les docs ont le `path=/docs/myDoc`))	Définit la version vers laquelle on navigue en priorité sur les sites versionnés et celle affichée par défaut dans les éléments de la barre de navigation de docs. Remarque : le chemin et le libellé de la dernière version sont configurables. Conseil : `lastVersion: 'current'` a un sens dans de nombreux cas.
`versions`	`Versions`	`{}`	Personnalisation indépendante des propriétés de chaque version.
`onlyIncludeVersions`	`string[]`	Toutes les versions disponibles	Inclut uniquement un sous-ensemble de toutes les versions disponibles. Conseil : limitez à 2 ou 3 versions pour améliorer le démarrage et le temps de compilation dans le dev et déployer des aperçus.

type EditUrlFunction = (params: {  version: string;  versionDocsDirPath: string;  docPath: string;  permalink: string;  locale: string;}) => string | undefined;
type PrefixParser = (  filename: string,) => {filename: string; numberPrefix?: number};
type SidebarGenerator = (generatorArgs: {  item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated"  version: {contentPath: string; versionName: string}; // the current version  docs: Array<{    id: string;    frontMatter: DocFrontMatter & Record<string, unknown>;    source: string;    sourceDirName: string;    sidebarPosition?: number | undefined;  }>; // toutes les docs de cette version (non filtrées)  numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin  defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus}) => Promise<SidebarItem[]>;
type Versions = Record<  string, // l'ID de la version  {    label: string; // le libellé de la version    path: string; // le chemin d'accès de la version    banner: 'none' | 'unreleased' | 'unmaintained'; // la bannière à afficher en haut d'un doc de cette version    badge: boolean; // affiche un badge avec le nom de la version en haut d'un doc de cette version    className; // ajoute un nom de classe personnalisé à l'élément <html> lors de la consultation des docs de cette version  }>;

Exemple de configuration#

Voici un exemple d'objet de configuration.

Vous pouvez le fournir en tant qu'options du preset ou options du plugin.

astuce

La plupart des utilisateurs de Docusaurus configurent ce plugin via les options du preset.

const config = {  path: 'docs',  // Cas d'utilisation simple : string editUrl  // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',  // Cas d'utilisation avancé : editUrl une fonction  editUrl: ({versionDocsDirPath, docPath}) =>    `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`,  editLocalizedFiles: false,  editCurrentVersion: false,  routeBasePath: 'docs',  include: ['**/*.md', '**/*.mdx'],  exclude: [    '**/_*.{js,jsx,ts,tsx,md,mdx}',    '**/_*/**',    '**/*.test.{js,jsx,ts,tsx}',    '**/__tests__/**',  ],  sidebarPath: 'sidebars.js',  sidebarItemsGenerator: async function ({    defaultSidebarItemsGenerator,    numberPrefixParser,    item,    version,    docs,  }) {    // Utilisez 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'},        ],      },    ];  },  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 de fichier nettoyé    if (numberPrefix) {      return {        numberPrefix,        filename: filename.replace(prefix, ''),      };    }    //Aucun préfixe de numéro trouvé    return {numberPrefix: undefined, filename};  },  docLayoutComponent: '@theme/DocPage',  docItemComponent: '@theme/DocItem',  remarkPlugins: [require('remark-math')],  rehypePlugins: [],  beforeDefaultRemarkPlugins: [],  beforeDefaultRehypePlugins: [],  showLastUpdateAuthor: false,  showLastUpdateTime: false,  disableVersioning: false,  includeCurrentVersion: true,  lastVersion: undefined,  versions: {    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',    },  },  onlyIncludeVersions: ['current', '1.0.0', '2.0.0'],};

Options du preset#

Si vous utilisez un preset, configurez ce plugin à travers les options du preset :

docusaurus.config.js

module.exports = {  presets: [    [      '@docusaurus/preset-classic',      {        docs: {          path: 'docs',          // ... objet de configuration ici        },      },    ],  ],};

Options du plugin#

Si vous utilisez un plugin autonome, fournissez des options directement au plugin :

docusaurus.config.js

module.exports = {  plugins: [    [      '@docusaurus/plugin-content-docs',      {        path: 'docs',        // ... objet de configuration ici      },    ],  ],};

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é.

Champs acceptés :

Nom	Type	Par défaut	Description
`id`	`string`	le chemin du fichier (y compris les dossiers, sans l'extension)	Un identifiant unique du doc.
`title`	`string`	Titre Markdown ou `id`	Le titre du texte 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.
`pagination_label`	`string`	`sidebar_label` ou `title`	Le texte utilisé dans le document pour les boutons suivant/précédent pour ce document.
`sidebar_label`	`string`	`title`	Le texte affiché dans la barre latérale du document pour ce document.
`sidebar_position`	`number`	Ordre par défaut	Contrôle la position d'un doc à l'intérieur de la barre latérale générée lorsque vous utilisez les éléments `autogenerated` de la barre latérale. Consultez aussi Métadonnées de la barre latérale générées automatiquement.
`hide_title`	`boolean`	`false`	Si vous voulez 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.
`hide_table_of_contents`	`boolean`	`false`	S'il faut cacher la table des matières à droite.
`parse_number_prefixes`	`boolean`	option `numberPrefixParser` du plugin	Si l'analyse des préfixes numériques est désactivée sur ce doc. Consultez aussi Utilisez les préfixes de nombre.
`custom_edit_url`	`string`	Calculé à l'aide de l'option `editUrl` du plugin	L'URL pour modifier ce document.
`keywords`	`string[]`	`undefined`	Balise meta de mots clés pour la page du document, pour les moteurs de recherche.
`description`	`string`	La première ligne du contenu Markdown	La description de votre document, qui deviendra
`<meta name="description" content="..."/>` et `<meta property="og:description" content="..."/>` dans `<head>`, utilisés par les moteurs de recherche.
`image`	`string`	`undefined`	Couverture ou image miniature qui sera utilisée lors de l'affichage du lien vers votre article.
`slug`	`string`	Chemin du fichier	Permet de personnaliser l'url du document (`/<routeBasePath>/<slug>`). Prise en charge de multiples formats : `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`.
`tags`	`Tag[]`	`undefined`	Une liste de chaînes ou d'objets de deux champs de chaîne `label` et `permalink` pour taguer vos docs.

type Tag = string | {label: string; permalink: string};

Exemple :

---id: doc-markdowntitle: Fonctionnalités Markdown de Docshide_title: falsehide_table_of_contents: falsesidebar_label: Markdownsidebar_position: 3pagination_label: Fonctionnalités Markdowncustom_edit_url: https://github.com/facebook/docusaurus/edit/main/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 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