Aller au contenu principal
Version : 2.0.0-beta.22 🚧

📩 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 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 :

NomTypePar défautDescription
pathstring'docs'Chemin vers le répertoire de contenu des docs sur le systÚme de fichiers, relatif au répertoire du site.
editUrlstring | EditUrlFunctionundefinedURL 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.
editLocalizedFilesbooleanfalseL'URL de modification ciblera le fichier localisé, au lieu du fichier original non localisé. Ignoré lorsque editUrl est une fonction.
editCurrentVersionbooleanfalseL'URL de modification ciblera toujours la version actuelle au lieu d'anciennes versions. Ignoré lorsque editUrl est une fonction.
routeBasePathstring'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.
tagsBasePathstring'tags'Route URL pour la page de la liste des tags de votre site. Il est préfixé par routeBasePath.
includestring[]['**/*.{md,mdx}']Tableau de patterns de glob correspondant aux fichiers Markdown Ă  construire, relatif au chemin de contenu.
excludestring[]Voir l'exemple de configurationTableau de patterns de glob correspondant aux fichiers Markdown à exclure. Sert d'affinement basé sur l'option include.
sidebarPathfalse | stringundefinedChemin vers la configuration de la barre latérale. Utilisez false pour désactiver les barres latérales, ou undefined pour créer une barre latérale entiÚrement générée automatiquement.
sidebarCollapsiblebooleantrueSi les catégories de la barre latérale sont repliables par défaut. Consultez aussi Catégories repliables
sidebarCollapsedbooleantrueSi les catégories de la barre latérale sont réduites par défaut. Consultez aussi Catégories développées par défaut
sidebarItemsGeneratorSidebarGeneratorOmisFonction utilisée pour remplacer les éléments de type 'autogenerated' avec 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
numberPrefixParserboolean | PrefixParserOmisLogique 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
docLayoutComponentstring'@theme/DocPage'Composant racine de mise en page de chaque page de doc. Fournit le contexte des données de version, et n'est pas démonté lors du changement de documentation.
docItemComponentstring'@theme/DocItem'Conteneur principal du document, avec table des matiĂšres, pagination, etc.
docTagsListComponentstring'@theme/DocTagsListPage'Composant racine de la page de la liste des tags
docTagDocListComponentstring'@theme/DocTagDocListPage'Composant racine de la page « des docs contenant le tag X ».
docCategoryGeneratedIndexComponentstring'@theme/DocCategoryGeneratedIndexPage'Composant racine de la page d'index des catégories générées.
remarkPluginsany[][]Plugins Remark passés à MDX.
rehypePluginsany[][]Plugins Rehype passés à MDX.
beforeDefaultRemarkPluginsany[][]Les plugins Remark personnalisés sont transmis à MDX avant les plugins Remark par défaut de Docusaurus.
beforeDefaultRehypePluginsany[][]Les plugins Rehype personnalisés sont transmis à MDX avant les plugins Rehype par défaut de Docusaurus.
showLastUpdateAuthorbooleanfalseAffichage ou non de l'auteur de la derniĂšre mise Ă  jour du doc.
showLastUpdateTimebooleanfalseAffichage ou non de la derniĂšre date de mise Ă  jour du doc.
disableVersioningbooleanfalseDĂ©sactive explicitement le versionnage mĂȘme lorsque plusieurs versions existent. Ainsi, le site n'inclura que la version actuelle. Une erreur se produira si includeCurrentVersion: false et disableVersioning: true.
includeCurrentVersionbooleantrueInclue la version « courante » de vos docs.
lastVersionstringPremiÚre version dans versions.jsonLa version vers laquelle on navigue en priorité et qui est affichée par défaut pour les éléments de la barre de navigation des docs.
onlyIncludeVersionsstring[]Toutes les versions disponiblesInclut uniquement un sous-ensemble de toutes les versions disponibles.
versionsVersionsConfig{}Personnalisation indépendante des propriétés de chaque version.

Types​

EditUrlFunction​

type EditUrlFunction = (params: {
version: string;
versionDocsDirPath: string;
docPath: string;
permalink: string;
locale: string;
}) => string | undefined;

PrefixParser​

type PrefixParser = (filename: string) => {
filename: string;
numberPrefix?: number;
};

SidebarGenerator​

type SidebarGenerator = (generatorArgs: {
/** L'élément de la barre latérale avec le type "autogenerated" à transformer. */
item: {type: 'autogenerated'; dirName: string};
/** Métadonnées utiles pour la version à laquelle appartient cette barre latérale. */
version: {contentPath: string; versionName: string};
/** Tous les docs de cette version (non filtré). */
docs: {
id: string;
title: string;
frontMatter: DocFrontMatter & Record<string, unknown>;
source: string;
sourceDirName: string;
sidebarPosition?: number | undefined;
}[];
/** Analyseur de nombres configuré pour ce plugin. */
numberPrefixParser: PrefixParser;
/** L'indexeur de catégorie par défaut que vous pouvez remplacer. */
isCategoryIndex: CategoryIndexMatcher;
/**
* la clé est le chemin relatif au répertoire de contenu du doc, la valeur est
* le contenu du fichier de métadonnées de la catégorie.
*/
categoriesMetadata: {[filePath: string]: CategoryMetadata};
/**
* Utile pour réutiliser/améliorer la logique de génération de la barre latérale par défaut à partir de
* Docusaurus.
*/
defaultSidebarItemsGenerator: SidebarGenerator;
// Renvoie un tableau d'Ă©lĂ©ments de la barre latĂ©rale — identique Ă  ce que vous pouvez dĂ©clarer dans
// sidebars.js, sauf pour les raccourcis. Voir https://docusaurus. o/docs/sidebar/items
}) => Promise<SidebarItem[]>;

type CategoryIndexMatcher = (param: {
/** Le nom du fichier, sans extension */
fileName: string;
/**
* La liste des répertoires, du niveau le plus bas au plus élevé.
* S'il n'y a pas de nom de répertoire, les répertoires sont ['.']
*/
directories: string[];
/** L'extension, avec un point au début */
extension: string;
}) => boolean;

VersionsConfig​

type VersionsConfig = {
[versionName: string]: {
/**
* Le chemin de base de la version, sera ajouté à `baseUrl` +
* `routeBasePath`.
*/
path?: string;
/** Le libellé de la version à utiliser dans les badges, les listes déroulantes, etc. */
label?: string;
/** La banniĂšre Ă  afficher en haut d'un doc de cette version. */
banner?: 'none' | 'unreleased' | 'unmaintained';
/** Affiche un badge avec le libellé de la version en haut de chaque doc. */
badge?: boolean;
/** Ajoute un nom de classe personnalisé à l'élément <html> de chaque doc */
className?: string;
};
};

Exemple de configuration​

Vous pouvez configurer ce plugin via les options du preset ou du plugin.

astuce

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

Si vous utilisez un preset, configurez ce plugin via le options du preset :

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
path: 'docs',
breadcrumbs: true,
// Cas simple : string editUrl
// editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
// Cas avancé : functional editUrl
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',
async sidebarItemsGenerator({
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
isCategoryIndex,
}) {
// Utilise les données fournies pour générer une section de la barre latérale personnalisée
return [
{type: 'doc', id: 'intro'},
{
type: 'category',
label: 'Tutorials',
items: [
{type: 'doc', id: 'tutorial1'},
{type: 'doc', id: 'tutorial2'},
],
},
];
},
numberPrefixParser(filename) {
// Implémentez votre propre logique pour extraire un préfixe de nombre éventuel
const numberPrefix = findNumberPrefix(filename);
// Préfixe trouvé : retourne le fichier avec le nom du 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'],
},
},
],
],
};

Markdown frontmatter​

Les documents Markdown peuvent utiliser les champs de métadonnées Markdown du frontmatter suivants, entourés par une ligne --- de chaque cÎté.

Champs acceptés :

NomTypePar défautDescription
idstringle chemin du fichier (y compris les dossiers, sans l'extension)Un ID unique du doc.
titlestringTitre Markdown ou idLe 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.
pagination_labelstringsidebar_label ou titleLe texte utilisé dans le document pour les boutons suivant/précédent pour ce document.
hide_titlebooleanfalseSi 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_contentsbooleanfalseS'il faut cacher la table des matiĂšres Ă  droite.
toc_min_heading_levelnumber2Le niveau de titre minimum affichĂ© dans la table des matiĂšres. Doit ĂȘtre compris entre 2 et 6 et infĂ©rieur ou Ă©gal Ă  la valeur maximale.
toc_max_heading_levelnumber3Le niveau de titre maximum affichĂ© dans la table des matiĂšres. Doit ĂȘtre compris entre 2 et 6.
pagination_nextstring | nullLe doc suivant dans la barre latéraleL'ID de la documentation à laquelle vous voulez que la pagination "Suivant" soit liée. Utilisez null pour désactiver l'affichage "Suivant" pour cette page.
pagination_prevstring | nullLe doc précédent dans la barre latéraleL'ID de la documentation à laquelle vous voulez que la pagination "Précédent" soit liée. Utilisez null pour désactiver l'affichage "Précédent" pour cette page.
parse_number_prefixesbooleanoption numberPrefixParser du pluginSi l'analyse des préfixes numériques est désactivée sur ce doc. Consultez aussi Utilisez les préfixes de nombre.
custom_edit_urlstringCalculé à l'aide de l'option editUrl du pluginL'URL pour modifier ce document.
keywordsstring[]undefinedBalise meta de mots clés pour la page du document, pour les moteurs de recherche.
descriptionstringLa premiÚre ligne du contenu MarkdownLa description de votre document, qui deviendra la <meta name="description" content="..."/> et <meta property="og:description" content="..."/> dans <head>, utilisé par les moteurs de recherche.
imagestringundefinedCouverture ou image miniature qui sera utilisée lors de l'affichage du lien vers votre article.
slugstringChemin du fichierPermet de personnaliser l'URL du document (/<routeBasePath>/<slug>). Prise en charge de multiples formats : slug: my-doc, slug: /my/path/myDoc, slug: /.
tagsTag[]undefinedUne liste de chaĂźnes ou d'objets de deux champs de chaĂźne label et permalink pour taguer vos docs.
draftbooleanfalseUn booléen pour indiquer qu'un document est en cours de rédaction. Les brouillons de document seront affichés uniquement lors du développement.
last_updateFileChangeundefinedPermet de remplacer l'auteur et/ou la date de la derniĂšre mise Ă  jour. La date peut ĂȘtre toute chaĂźne de date interprĂ©table.
type Tag = string | {label: string; permalink: string};
type FileChange = {date: string; author: string};

Exemple :

---
id: doc-markdown
title: Docs fonctionnalités Markdown
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown
sidebar_position: 3
pagination_label: Fonctionnalités Markdown
custom_edit_url: https://github.com/facebook/docusaurus/edit/main/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
last_update:
date: 1/1/2000
author: nom auteur personnalisé
---

# 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/[versionName]

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