Aller au contenu principal
Version: 2.0.0-beta.7

📩 plugin-content-blog

Fournit la fonctionnalité Blog et c'est le plugin par défaut du blog de Docusaurus.

Installation

npm install --save @docusaurus/plugin-content-blog
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'blog'Chemin vers le répertoire de contenu du blog sur le systÚme de fichiers, relatif au répertoire du site.
editUrl!!crwdBlockTags_263_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.
blogTitlestring'Blog'Titre de la page du blog pour un meilleur référencement.
blogDescriptionstring'Blog'Description de la page du blog pour un meilleur référencement.
blogSidebarCount!!crwdBlockTags_264_sgaTkcolBdwrc!!5Nombre d'éléments à afficher dans la barre latérale du blog. 'ALL' pour afficher tous les articles du blog; 0 pour désactiver
blogSidebarTitlestring'Recent posts'Titre de la barre latérale du blog.
routeBasePathstring'blog'Route URL pour la section blog de votre site. NE PAS inclure un slash de fin. Utilisez / pour mettre le blog Ă  la racine du chemin.
tagsBasePathstring'tags'route URL pour la page de la liste des tags de votre site. Il est préfixé par routeBasePath.
archiveBasePathstring'/archive'Route URL pour la section archive du blog de votre site. Il est préfixé par routeBasePath. NE PAS inclure un slash de fin.
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.
postsPerPage!!crwdBlockTags_265_sgaTkcolBdwrc!!10Nombre d'articles Ă  afficher par page dans la liste. Utilisez 'ALL' pour afficher tous les articles sur une page de liste.
blogListComponentstring'@theme/BlogListPage'Composant racine de la page de liste du blog.
blogPostComponentstring'@theme/BlogPostPage'Composant racine de chaque page d'article du blog.
blogTagsListComponentstring'@theme/BlogTagsListPage'Composant racine de la page de la liste des tags
blogTagsPostsComponentstring'@theme/BlogTagsPostsPage'Composant racine de la page "articles 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.
truncateMarkerstring/<!--\s*(truncate)\s*-->/Truncate marker, peut ĂȘtre un regex ou une chaĂźne.
showReadingTimebooleantrueAffiche le temps de lecture estimé pour l'article du blog.
authorsMapPathstring'authors.yml'Chemin vers le fichier map des auteurs, relatif au rĂ©pertoire de contenu du blog spĂ©cifiĂ© avec path. Peut Ă©galement ĂȘtre un fichier json.
feedOptionsVoir ci-dessous{type: ['rss', 'atom']}Flux du blog. Si undefined, aucun flux rss ne sera généré.
feedOptions.type!!crwdBlockTags_266_sgaTkcolBdwrc!! (ou tableau d'options multiples)ObligatoireType de flux à générer.
feedOptions.titlestringsiteConfig.titleTitre du flux.
feedOptions.descriptionstring!!crwdBlockTags_267_sgaTkcolBdwrc!!Description du flux.
feedOptions.copyrightstringundefinedMessage de copyright.
feedOptions.languagestring (Voir documentation pour les valeurs possibles)undefinedMétadonnées de langue du flux.
type EditUrlFunction = (params: {
blogDirPath: string;
blogPath: string;
permalink: string;
locale: string;
}) => string | undefined;

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: 'blog',
// Cas d'utilisation simple : string editUrl
// editUrl : 'https://github.com/facebook/docusaurus/edit/main/website/',
// Cas d'utilisation avancé : editUrl avec une fonction
editUrl: ({locale, blogDirPath, blogPath, permalink}) => {
return `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`;
},
editLocalizedFiles: false,
blogTitle: 'Blog title',
blogDescription: 'Blog',
blogSidebarCount: 5,
blogSidebarTitle: 'All our posts',
routeBasePath: 'blog',
include: ['**/*.{md,mdx}'],
exclude: [
'**/_*.{js,jsx,ts,tsx,md,mdx}',
'**/_*/**',
'**/*.test.{js,jsx,ts,tsx}',
'**/__tests__/**',
],
postsPerPage: 10,
blogListComponent: '@theme/BlogListPage',
blogPostComponent: '@theme/BlogPostPage',
blogTagsListComponent: '@theme/BlogTagsListPage',
blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
remarkPlugins: [require('remark-math')],
rehypePlugins: [],
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
truncateMarker: /<!--\s*(truncate)\s*-->/,
showReadingTime: true,
feedOptions: {
type: '',
title: '',
description: '',
copyright: '',
language: undefined,
},
};

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',
{
blog: {
path: 'blog',
// ... 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-blog',
{
path: 'blog',
// ... 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
authorsAuteursundefinedListe des auteurs de l'article du blog (ou auteur unique). Lisez le guide authors pour plus d'explications. PrĂ©fĂ©rez authors aux champs FrontMatter author_*, mĂȘme pour les articles du blog avec un seul auteur.
authorstringundefined⚠ PrĂ©fĂ©rez l'utilisation de authors. Le nom de l'auteur de l'article du blog.
author_urlstringundefined⚠ PrĂ©fĂ©rez l'utilisation de authors. L'URL Ă  laquelle le nom de l'auteur sera liĂ©. Il peut s'agir de l'URL d'un profil GitHub, Twitter, Facebook, etc.
author_image_urlstringundefined⚠ PrĂ©fĂ©rez l'utilisation de authors. L'URL de l'image miniature de l'auteur.
author_titlestringundefined⚠ PrĂ©fĂ©rez l'utilisation de authors. Une description de l'auteur.
titlestringMarkdown titleLe titre de l'article du blog.
datestringNom du fichier ou heure de crĂ©ation du fichierLa date de crĂ©ation de l'article du blog. Si non spĂ©cifiĂ©, ceci peut ĂȘtre extrait du nom du fichier ou du dossier, par exemple 2021-04-15-blog-post.mdx, 2021-04-15-blog-post/index.mdx, 2021/04/15/blog-post.mdx. Sinon, c'est l'heure de crĂ©ation du fichier Markdown.
tagsTag[]undefinedUne liste de chaĂźnes ou d'objets de deux champs de chaĂźne label et permalink pour taguer votre article.
draftbooleanfalseUn boolĂ©en pour indiquer que l'article du blog est en cours de rĂ©daction et ne doit donc pas encore ĂȘtre publiĂ©. Cependant, les brouillons du blog seront affichĂ©s pendant le dĂ©veloppement.
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.
keywordsstring[]undefinedBalise meta des mots clés, qui deviendra <meta name="keywords" content="keyword1,keyword2,..."/> dans <head>, utilisé par les moteurs de recherche.
descriptionstringLa premiĂšre ligne du contenu MarkdownLa 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.
imagestringundefinedCouverture ou image miniature qui sera utilisée lors de l'affichage du lien vers votre article.
slugstringChemin du fichierPermet de personnaliser l'url de l'article du blog (/<routeBasePath>/<slug>). Prise en charge de multiples formats : slug: my-blog-post, slug: /my/path/to/blog/post, slug: /.
type Tag = string | {label: string; permalink: string};

// Une clé d'auteur fait référence à un auteur du fichier authors.yml du plugin global
type AuthorKey = string;

type Author = {
key?: AuthorKey;
name: string;
title?: string;
url?: string;
image_url?: string;
};

// Le champ authors de FrontMatter permet plusieurs formes possibles
type Authors = AuthorKey | Author | (AuthorKey | Author)[];

Exemple :

---
title: Bienvenue Docusaurus v2
authors:
- slorber
- yangshun
- name: Joel Marcey
title: Co-créateur de Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
tags: [hello, docusaurus-v2]
description: Ceci est mon premier article sur Docusaurus 2.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
Un article Markdown du blog

i18n

Lisez l’introduction i18n en premier.

Emplacement des fichiers de traduction

  • Chemin de base : website/i18n/<locale>/docusaurus-plugin-content-blog
  • Chemin d'accĂšs multi-instance : website/i18n/<locale>/docusaurus-plugin-content-blog-<pluginId>
  • Fichiers JSON : extrait avec docusaurus write-translations
  • Fichiers Markdown : website/i18n/<locale>/docusaurus-plugin-content-blog

Exemple de structure du systĂšme de fichiers

website/i18n/<locale>/docusaurus-plugin-content-blog
│
│ # traductions pour website/blog
├── authors.yml
├── first-blog-post.md
├── second-blog-post.md
│
│ # traductions pour des options du plugin qui seront rendues
└── options.json