📦 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

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

Yarn

yarn add @docusaurus/plugin-content-blog

pnpm

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*-->/	\{\/\*\s*truncate\s*\*\/\}/
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.limit	number | null | false	20	Limite le flux au nombre spécifié d'articles, false ou null pour avoir toutes les entrées. Par défaut, 20.
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.

Preset options

If you use a preset, configure this plugin through the preset options:

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('./my-remark-plugin')],
          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,
              });
            },
          },
        },
      },
    ],
  ],
};

Plugin options

If you are using a standalone plugin, provide options directly to the 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('./my-remark-plugin')],
        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	Les brouillons d'articles du blog seront disponibles uniquement lors du développement.
unlisted	boolean	false	Les articles de blog non listés seront disponibles à la fois en développement et en production. Ils seront « cachés » en production, non indexés, exclus des sitemaps, et ne peuvent être consultés que par les utilisateurs ayant un lien direct.
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
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.
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