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
Yarn
pnpm

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

yarn add @docusaurus/plugin-content-blog

pnpm add @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 :

Nom	Type	Par défaut	Description
`path`	`string`	`'blog'`	Chemin vers le répertoire de contenu du blog sur le système de fichiers, relatif au répertoire du site.
`editUrl`	`string \| EditUrlFn`	`undefined`	URL 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.
`editLocalizedFiles`	`boolean`	`false`	L'URL de modification ciblera le fichier localisé, au lieu du fichier original non localisé. Ignored when `editUrl` is a function.
`blogTitle`	`string`	`'Blog'`	Titre de la page du blog pour un meilleur référencement.
`blogDescription`	`string`	`'Blog'`	Description de la page du blog pour un meilleur référencement.
`blogSidebarCount`	`number \| 'ALL'`	`5`	Nombre d'articles du blog à afficher dans la barre latérale du blog. `'ALL'` to show all blog posts; `0` to disable.
`blogSidebarTitle`	`string`	`'Recent posts'`	Titre de la barre latérale du blog.
`routeBasePath`	`string`	`'blog'`	Route URL pour la section blog de votre site. DO NOT include a trailing slash. Use `/` to put the blog at root path.
`tagsBasePath`	`string`	`'tags'`	Route URL pour la section des tags de votre blog. Will be appended to `routeBasePath`. DO NOT include a trailing slash.
`archiveBasePath`	`string \| 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.
`include`	`string[]`	`['*/.{md,mdx}']`	Tableau de patterns de glob correspondant aux fichiers Markdown à construire, relatif au chemin de contenu.
`exclude`	`string[]`	See example configuration	Tableau de patterns de glob correspondant aux fichiers Markdown à exclure. Serves as refinement based on the `include` option.
`postsPerPage`	`number \| 'ALL'`	`10`	Nombre d'articles à afficher par page dans la liste. Use `'ALL'` to display all posts on one listing page.
`blogListComponent`	`string`	`'@theme/BlogListPage'`	Composant racine de la page de liste du blog.
`blogPostComponent`	`string`	`'@theme/BlogPostPage'`	Composant racine de chaque page d'article du blog.
`blogTagsListComponent`	`string`	`'@theme/BlogTagsListPage'`	Composant racine de la page de la liste des tags.
`blogTagsPostsComponent`	`string`	`'@theme/BlogTagsPostsPage'`	Composant racine de la page « articles contenant le tag ».
`blogArchiveComponent`	`string`	`'@theme/BlogArchivePage'`	Composant racine de la page d'archive du blog.
`remarkPlugins`	`any[]`	`[]`	Plugins Remark passés à MDX.
`rehypePlugins`	`any[]`	`[]`	Plugins Rehype passés à MDX.
`beforeDefaultRemarkPlugins`	`any[]`	`[]`	Les plugins Remark personnalisés sont transmis à MDX avant les plugins Remark par défaut de Docusaurus.
`beforeDefaultRehypePlugins`	`any[]`	`[]`	Les plugins Rehype personnalisés sont transmis à MDX avant les plugins Rehype par défaut de Docusaurus.
`truncateMarker`	`RegExp`	`/<!--\s(truncate)\s-->/`	Marqueur de troncature marquant la fin du résumé.
`showReadingTime`	`boolean`	`true`	Affiche le temps de lecture estimé pour l'article du blog.
`readingTime`	`ReadingTimeFn`	Le temps de lecture par défaut	Un callback pour personnaliser le nombre du temps de lecture affiché.
`authorsMapPath`	`string`	`'authors.yml'`	Chemin vers le fichier map des auteurs, relatif au répertoire de contenu du blog.
`feedOptions`	See below	`{type: ['rss', 'atom']}`	Flux du blog.
`feedOptions.type`	`FeedType \| FeedType[] \| 'all' \| null`	Required	Type de flux à générer. Use `null` to disable generation.
`feedOptions.createFeedItems`	`CreateFeedItemsFn \| undefined`	`undefined`	Une fonction optionnelle qui peut être utilisée pour transformer et / ou filtrer les éléments du flux.
`feedOptions.title`	`string`	`siteConfig.title`	Titre du flux.
`feedOptions.description`	`string`	`${siteConfig.title} Blog`	Description du flux.
`feedOptions.copyright`	`string`	`undefined`	Message de copyright.
`feedOptions.language`	`string` (See documentation for possible values)	`undefined`	Mé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.

Options du preset
Options du plugin

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,
              });
            },
          },
        },
      },
    ],
  ],
};

Si vous utilisez un plugin autonome, fournissez des options directement au plugin :

docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-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 :

Nom	Type	Par défaut	Description
`authors`	`Authors`	`undefined`	Liste 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.
`author`	`string`	`undefined`	⚠️ Prefer using `authors`. Le nom de l'auteur de l'article du blog.
`author_url`	`string`	`undefined`	⚠️ 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_url`	`string`	`undefined`	⚠️ Prefer using `authors`. L'URL de l'image miniature de l'auteur.
`author_title`	`string`	`undefined`	⚠️ Prefer using `authors`. Une description de l'auteur.
`title`	`string`	Titre du Markdown	Le titre de l'article du blog.
`date`	`string`	Nom du fichier ou heure de création du fichier	La 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.
`tags`	`Tag[]`	`undefined`	A list of strings or objects of two string fields `label` and `permalink` to tag to your post.
`draft`	`boolean`	`false`	Un 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_contents`	`boolean`	`false`	S'il faut cacher la table des matières à droite.
`toc_min_heading_level`	`number`	`2`	Le 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_level`	`number`	`3`	Le niveau de titre maximum affiché dans la table des matières. Doit être compris entre 2 et 6.
`keywords`	`string[]`	`undefined`	Keywords meta tag, which will become the `<meta name="keywords" content="keyword1,keyword2,..."/>` in `<head>`, used by search engines.
`description`	`string`	La première ligne du contenu Markdown	The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines.
`image`	`string`	`undefined`	Couverture ou image miniature qui sera utilisée lors de l'affichage du lien vers votre article.
`slug`	`string`	Chemin du fichier	Allows 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

📦 plugin-content-blog

Installation​

Configuration​

Types​

EditUrlFn​

ReadingTimeFn​

FeedType​

CreateFeedItemsFn​

Example configuration​

Markdown front matter​

i18n​

Translation files location​

Example file-system structure​