Aller au contenu principal
Version : 2.4.0

📦 plugin-content-docs

Provides the Docs functionality and is the default docs plugin for Docusaurus.

Installation​

npm install --save @docusaurus/plugin-content-docs
astuce

If you use the preset @docusaurus/preset-classic, you don't need to install this plugin as a dependency.

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. The final URL is computed by 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é. Ignored when editUrl is a function.
editCurrentVersionbooleanfalseL'URL de modification ciblera toujours la version actuelle au lieu d'anciennes versions. Ignored when editUrl is a function.
routeBasePathstring'docs'Route URL pour la section des docs de votre site. DO NOT include a trailing slash. Use / for shipping docs without base path.
tagsBasePathstring'tags'Route URL pour la page de la liste des tags de votre site. It is prepended to the routeBasePath.
includestring[]['**/*.{md,mdx}']Tableau de patterns de glob correspondant aux fichiers Markdown à construire, relatif au chemin de contenu.
excludestring[]See example configurationTableau de patterns de glob correspondant aux fichiers Markdown à exclure. Serves as refinement based on the include option.
sidebarPathfalse | stringundefinedChemin vers la configuration de la barre latérale. Use false to disable sidebars, or undefined to create a fully autogenerated sidebar.
sidebarCollapsiblebooleantrueSi les catégories de la barre latérale sont repliables par défaut. See also Collapsible categories
sidebarCollapsedbooleantrueSi les catégories de la barre latérale sont réduites par défaut. See also Expanded categories by default
sidebarItemsGeneratorSidebarGeneratorOmittedFunction used to replace the sidebar items of type 'autogenerated' with real sidebar items (docs, categories, links...). See also Customize the sidebar items generator
numberPrefixParserboolean | PrefixParserOmittedLogique d'analyse personnalisée pour extraire les préfixes numériques des noms de fichiers. Use false to disable this behavior and leave the docs untouched, and true to use the default parser. See also Using number prefixes
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. Will error if includeCurrentVersion: false and disableVersioning: true.
includeCurrentVersionbooleantrueInclue la version « courante » de vos docs.
lastVersionstringFirst version in 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: {
/** The sidebar item with type "autogenerated" to be transformed. */
item: {type: 'autogenerated'; dirName: string};
/** Useful metadata for the version this sidebar belongs to. */
version: {contentPath: string; versionName: string};
/** All the docs of that version (unfiltered). */
docs: {
id: string;
title: string;
frontMatter: DocFrontMatter & Record<string, unknown>;
source: string;
sourceDirName: string;
sidebarPosition?: number | undefined;
}[];
/** Number prefix parser configured for this plugin. */
numberPrefixParser: PrefixParser;
/** The default category index matcher which you can override. */
isCategoryIndex: CategoryIndexMatcher;
/**
* key is the path relative to the doc content directory, value is the
* category metadata file's content.
*/
categoriesMetadata: {[filePath: string]: CategoryMetadata};
/**
* Useful to re-use/enhance the default sidebar generation logic from
* Docusaurus.
*/
defaultSidebarItemsGenerator: SidebarGenerator;
// Returns an array of sidebar items — same as what you can declare in
// sidebars.js, except for shorthands. See https://docusaurus.io/docs/sidebar/items
}) => Promise<SidebarItem[]>;

type CategoryIndexMatcher = (param: {
/** The file name, without extension */
fileName: string;
/**
* The list of directories, from lowest level to highest.
* If there's no dir name, directories is ['.']
*/
directories: string[];
/** The extension, with a leading dot */
extension: string;
}) => boolean;

VersionsConfig​

type VersionConfig = {
/**
* The base path of the version, will be appended to `baseUrl` +
* `routeBasePath`.
*/
path?: string;
/** The label of the version to be used in badges, dropdowns, etc. */
label?: string;
/** The banner to show at the top of a doc of that version. */
banner?: 'none' | 'unreleased' | 'unmaintained';
/** Show a badge with the version label at the top of each doc. */
badge?: boolean;
/** Prevents search engines from indexing this version */
noIndex?: boolean;
/** Add a custom class name to the <html> element of each doc */
className?: string;
};

type VersionsConfig = {[versionName: string]: VersionConfig};

Example 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,
// Simple use-case: string editUrl
// editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
// Advanced use-case: 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,
}) {
// Use the provided data to generate a custom sidebar slice
return [
{type: 'doc', id: 'intro'},
{
type: 'category',
label: 'Tutorials',
items: [
{type: 'doc', id: 'tutorial1'},
{type: 'doc', id: 'tutorial2'},
],
},
];
},
numberPrefixParser(filename) {
// Implement your own logic to extract a potential number prefix
const numberPrefix = findNumberPrefix(filename);
// Prefix found: return it with the cleaned filename
if (numberPrefix) {
return {
numberPrefix,
filename: filename.replace(prefix, ''),
};
}
// No number prefix found
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 front matter​

Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line --- on either side.

Champs acceptés :

NomTypePar défautDescription
idstringle chemin du fichier (y compris les dossiers, sans l'extension)Un ID unique du doc.
titlestringMarkdown title or 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 or titleLe texte utilisé dans le document pour les boutons suivant/précédent pour ce document.
displayed_sidebarstringundefinedForcer l'affichage d'une barre latérale donnée lors de la navigation dans le document courant. Read the multiple sidebars guide for details.
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. Use null to disable showing "Next" for this 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. Use null to disable showing "Previous" for this page.
parse_number_prefixesbooleannumberPrefixParser plugin optionSi l'analyse des préfixes numériques est désactivée sur ce doc. See also Using number prefixes.
custom_edit_urlstringComputed using the editUrl plugin optionL'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 MarkdownThe description of your document, which will become the <meta name="description" content="..."/> and <meta property="og:description" content="..."/> in <head>, used by search engines.
imagestringundefinedCouverture ou image miniature qui sera utilisée lors de l'affichage du lien vers votre article.
slugstringChemin du fichierAllows to customize the document URL (/<routeBasePath>/<slug>). Support multiple patterns: slug: my-doc, slug: /my/path/myDoc, slug: /.
tagsTag[]undefinedA list of strings or objects of two string fields label and permalink to tag to your 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. Date can be any parsable date string.
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​

Read the i18n introduction first.

Translation files location​

  • Base path: website/i18n/[locale]/docusaurus-plugin-content-docs
  • Multi-instance path: website/i18n/[locale]/docusaurus-plugin-content-docs-[pluginId]
  • JSON files: extracted with docusaurus write-translations
  • Markdown files: website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]

Example file-system structure​

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