Aller au contenu principal
Version : 2.4.0

📦 plugin-content-blog

Provides the Blog feature and is the default blog plugin for Docusaurus.

some features production only

The feed feature works by extracting the build output, and is only active in production.

Installation​

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

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

You can configure this plugin through the preset options.

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.
editUrlstring | EditUrlFnundefinedURL de base pour modifier votre site. The final URL is computed by editUrl + relativePostPath. 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.
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.
blogSidebarCountnumber | 'ALL'5Nombre d'articles du blog à afficher dans la barre latérale du blog. 'ALL' to show all blog posts; 0 to disable.
blogSidebarTitlestring'Recent posts'Titre de la barre latérale du blog.
routeBasePathstring'blog'Route URL pour la section blog de votre site. DO NOT include a trailing slash. Use / to put the blog at root path.
tagsBasePathstring'tags'Route URL pour la section des tags de votre blog. Will be appended to routeBasePath. DO NOT include a trailing slash.
archiveBasePathstring | null'archive'Route d'URL pour la section archive de votre blog. Will be appended to routeBasePath. DO NOT include a trailing slash. Use null to disable generation of archive.
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.
postsPerPagenumber | 'ALL'10Nombre d'articles à afficher par page dans la liste. Use 'ALL' to display all posts on one listing page.
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 ».
blogArchiveComponentstring'@theme/BlogArchivePage'Composant racine de la page d'archive du blog.
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.
truncateMarkerRegExp/<!--\s*(truncate)\s*-->/Marqueur de troncature marquant la fin du résumé.
showReadingTimebooleantrueAffiche le temps de lecture estimé pour l'article du blog.
readingTimeReadingTimeFnLe temps de lecture par défautUn callback pour personnaliser le nombre du temps de lecture affiché.
authorsMapPathstring'authors.yml'Chemin vers le fichier map des auteurs, relatif au répertoire de contenu du blog.
feedOptionsSee below{type: ['rss', 'atom']}Flux du blog.
feedOptions.typeFeedType | FeedType[] | 'all' | nullRequiredType de flux à générer. Use null to disable generation.
feedOptions.createFeedItemsCreateFeedItemsFn | undefinedundefinedUne fonction optionnelle qui peut être utilisée pour transformer et / ou filtrer les éléments du flux.
feedOptions.titlestringsiteConfig.titleTitre du flux.
feedOptions.descriptionstring`${siteConfig.title} Blog`Description du flux.
feedOptions.copyrightstringundefinedMessage de copyright.
feedOptions.languagestring (See documentation for possible values)undefinedMétadonnées de langue du flux.
sortPosts'descending' | 'ascending' 'descending'Détermine l'orientation du tri des articles du blog.

Types​

EditUrlFn​

type EditUrlFunction = (params: {
blogDirPath: string;
blogPath: string;
permalink: string;
locale: string;
}) => string | undefined;

ReadingTimeFn​

type ReadingTimeOptions = {
wordsPerMinute: number;
wordBound: (char: string) => boolean;
};

type ReadingTimeCalculator = (params: {
content: string;
frontMatter?: BlogPostFrontMatter & Record<string, unknown>;
options?: ReadingTimeOptions;
}) => number;

type ReadingTimeFn = (params: {
content: string;
frontMatter: BlogPostFrontMatter & Record<string, unknown>;
defaultReadingTime: ReadingTimeCalculator;
}) => number | undefined;

FeedType​

type FeedType = 'rss' | 'atom' | 'json';

CreateFeedItemsFn​

type CreateFeedItemsFn = (params: {
blogPosts: BlogPost[];
siteConfig: DocusaurusConfig;
outDir: string;
defaultCreateFeedItemsFn: CreateFeedItemsFn;
}) => Promise<BlogFeedItem[]>;

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',
{
blog: {
path: 'blog',
// Simple use-case: string editUrl
// editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
// Advanced use-case: functional editUrl
editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
`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,
createFeedItems: async (params) => {
const {blogPosts, defaultCreateFeedItems, ...rest} = params;
return defaultCreateFeedItems({
// keep only the 10 most recent blog posts in the feed
blogPosts: blogPosts.filter((item, index) => index < 10),
...rest,
});
},
},
},
},
],
],
};

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
authorsAuthorsundefinedListe des auteurs de l'article du blog (ou auteur unique). Read the authors guide for more explanations. Prefer authors over the author_* front matter fields, even for single author blog posts.
authorstringundefined⚠️ Prefer using authors. Le nom de l'auteur de l'article du blog.
author_urlstringundefined⚠️ Prefer using 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⚠️ Prefer using authors. L'URL de l'image miniature de l'auteur.
author_titlestringundefined⚠️ Prefer using authors. Une description de l'auteur.
titlestringTitre du MarkdownLe 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. If not specified, this can be extracted from the file or folder name, e.g, 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[]undefinedA list of strings or objects of two string fields label and permalink to tag to your post.
draftbooleanfalseUn booléen pour indiquer que l'article du blog est en cours de rédaction. Les brouillons d'articles du blog seront affichés uniquement lors du développement.
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.
keywordsstring[]undefinedKeywords meta tag, which will become the <meta name="keywords" content="keyword1,keyword2,..."/> in <head>, used by search engines.
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 blog post URL (/<routeBasePath>/<slug>). Support multiple patterns: 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 du frontMatter permet plusieurs formes possibles
type Authors = AuthorKey | Author | (AuthorKey | Author)[];

Exemple :

---
title: Welcome Docusaurus v2
authors:
- slorber
- yangshun
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
tags: [hello, docusaurus-v2]
description: This is my first post on Docusaurus 2.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

A Markdown blog post

i18n​

Read the i18n introduction first.

Translation files location​

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

Example file-system structure​

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