Aller au contenu principal
Version: 2.0.0-beta.9

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

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 les données sur le systÚme de fichier par rapport au répertoire du site.
editUrl!!crwdBlockTags_256_sgaTkcolBdwrc!!undefinedURL 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}']Les fichiers correspondants seront inclus et traités.
excludestring[]Voir l'exemple de configurationAucune route ne sera créée pour les fichiers correspondants.
sidebarPath!!crwdBlockTags_257_sgaTkcolBdwrc!!undefined (crée la barre latérale générée automatiquement)Chemin vers la configuration de la barre latérale.
sidebarCollapsiblebooleantrueSi les catégories de la barre latérale sont réduites 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' 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_258_sgaTkcolBdwrc!!OmisLogique 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.
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 ».
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Ă©sactiver explicitement la fonction de versionnage mĂȘme avec des versions. Cela n'inclura que la version « courante » (le rĂ©pertoire /docs).
includeCurrentVersionbooleantrueInclue 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.
lastVersionstringcurrent (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.
versionsVersions{}Personnalisation indépendante des propriétés de chaque version.
onlyIncludeVersionsstring[]Toutes les versions disponiblesInclut 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}; // l'élément de la barre latérale avec le type "autogenerated".
version: {contentPath: string; versionName: string}; // la version actuelle
docs: Array<{
id: string;
frontMatter: DocFrontMatter & Record<string, unknown>;
source: string;
sourceDirName: string;
sidebarPosition?: number | undefined;
}>; // toutes les docs de cette version (non filtrés)
numberPrefixParser: PrefixParser; // numberPrefixParser configuré pour ce plugin
defaultSidebarItemsGenerator: SidebarGenerator; // utile pour réutiliser/améliorer la logique de génération de barre latérale par défaut de Docusaurus
}) => Promise<SidebarItem[]>;

type Versions = Record<
string, // the version's ID
{
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 document de cette version
badge: boolean; // afficher un badge avec le nom de la version en haut d'un document de cette version
className; // ajouter un nom de classe personnalisé à l'élément <html> lors de la navigation dans les 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.

tip

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 :

NomTypePar défautDescription
idstringle chemin du fichier (y compris les dossiers, sans l'extension)Un identifiant unique du doc.
titlestringTitre Markdown ou idLe 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_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 minimal 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 maximum de titre affichĂ© dans la table des matiĂšres. Doit ĂȘtre compris entre 2 et 6.
pagination_next!!crwdBlockTags_322_sgaTkcolBdwrc!!Le 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_prev!!crwdBlockTags_323_sgaTkcolBdwrc!!Le 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.
descriptionstringThe first line of Markdown contentThe 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.
slugstringFile pathAllows to customize the document url (/<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.
type Tag = string | {label: string; permalink: string};

Exemple :

---
id: doc-markdown
title: Docs Markdown Features
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown
sidebar_position: 3
pagination_label: Markdown features
custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md
description: How do I find you when I cannot solve this problem
keywords:
- docs
- docusaurus
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
---
# Markdown Features

My Document Markdown content

i18n

Lisez l’introduction i18n en premier.

Emplacement des fichiers de traduction

  • Base path: website/i18n/<locale>/docusaurus-plugin-content-docs
  • Multi-instance path: website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>
  • Fichiers JSON : extrait avec docusaurus write-translations
  • Markdown files: website/i18n/<locale>/docusaurus-plugin-content-docs/<version>

Exemple de structure du systĂšme de fichiers

website/i18n/<locale>/docusaurus-plugin-content-docs
│
│ # translations for website/docs
├── current
│   ├── api
│   │   └── config.md
│   └── getting-started.md
├── current.json
│
│ # translations for website/versioned_docs/version-1.0.0
├── version-1.0.0
│   ├── api
│   │   └── config.md
│   └── getting-started.md
└── version-1.0.0.json