Aller au contenu principal
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 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