Version : Canary 🚧

📦 plugin-content-blog

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

certaines fonctionnalités uniquement en production

La fonctionnalité flux fonctionne en extrayant la sortie de compilation, et n'est active qu'en 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

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 :

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. L'URL finale est calculée par `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é. Ignoré lorsque `editUrl` est une fonction.
`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'` pour montrer tous les articles du blog; `0` pour désactiver.
`blogSidebarTitle`	`string`	`'Articles récents'`	Titre de la barre latérale du blog.
`routeBasePath`	`string`	`'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.
`tagsBasePath`	`string`	`'tags'`	Route URL pour la section des tags de votre blog. Sera ajouté à `routeBasePath`.
`pageBasePath`	`string`	`'page'`	Route URL pour la section des pages de votre blog. Sera ajouté à `routeBasePath`.
`archiveBasePath`	`string \| null`	`'archive'`	Route d'URL pour la section archive de votre blog. Sera ajouté à `routeBasePath`. NE PAS inclure un slash de fin. Utilisez `null` pour désactiver la génération d'archives.
`authorsBasePath`	`string`	`'authors'`	URL route for the authors pages of your blog. Will be appended to `path`.
`include`	`string[]`	`['*/.{md,mdx}']`	Tableau de patterns de glob correspondant aux fichiers Markdown à construire, relatif au chemin de contenu.
`exclude`	`string[]`	Voir l'exemple de configuration	Tableau de patterns de glob correspondant aux fichiers Markdown à exclure. Sert d'affinement basé sur l'option `include`.
`postsPerPage`	`number \| 'ALL'`	`10`	Nombre d'articles à afficher par page dans la liste. Utilisez `'ALL'` pour afficher tous les articles sur une page de liste.
`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.
`blogAuthorsPostsComponent`	`string`	`'@theme/Blog/Pages/BlogAuthorsPostsPage'`	Root component of the blog author page.
`blogAuthorsListComponent`	`string`	`'@theme/Blog/Pages/BlogAuthorsListPage'`	Root component of the blog authors page index.
`remarkPlugins`	`any[]`	`[]`	Plugins Remark passés à MDX.
`rehypePlugins`	`any[]`	`[]`	Plugins Rehype passés à MDX.
`rehypePlugins`	`any[]`	`[]`	Recma plugins passed to 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`	`/<!--\struncate\s-->/` \	`\{\/\\struncate\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`	Voir ci-dessous	`{type: ['rss', 'atom']}`	Flux du blog.
`feedOptions.type`	`FeedType \| FeedType[] \| 'all' \| null`	Obligatoire	Type de flux à générer. Utilisez `null` pour désactiver la génération.
`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é de messages, `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.xslt`	`boolean \| FeedXSLTOptions`	`undefined`	Message de copyright.
`feedOptions.language`	`string` (Voir la documentation pour les valeurs possibles)	`undefined`	Métadonnées de langue du flux.
`sortPosts`	`'descending' \| 'ascending'`	`'descending'`	Détermine l'orientation du tri des articles du blog.
`processBlogPosts`	`ProcessBlogPostsFn`	`undefined`	Une fonction facultative qui peut être utilisée pour transformer les articles de blog (filtre, modification, suppression, etc...).
`showLastUpdateAuthor`	`boolean`	`false`	Affichage ou non de l'auteur de la dernière mise à jour de l'article du blog.
`showLastUpdateTime`	`boolean`	`false`	Affichage ou non de la dernière date de mise à jour de l'article du blog. Cela nécessite l'accès à l'historique git pendant la construction, et ne fonctionnera donc pas correctement avec des clones superficiels (un défaut courant pour les systèmes de CI). Avec GitHub `actions/checkout`, utilisez `fetch-depth: 0`.
`tags`	`string \| false \| null \| undefined`	`tags.yml`	Path to the YAML tags file listing pre-defined tags. Relative to the blog content directory.
`onInlineTags`	`'ignore' \| 'log' \| 'warn' \| 'throw'`	`warn`	The plugin behavior when blog posts contain inline tags (not appearing in the list of pre-defined tags, usually `tags.yml`).
`onUntruncatedBlogPosts`	`'ignore' \| 'log' \| 'warn' \| 'throw'`	`warn`	The plugin behavior when blog posts do not contain a truncate marker.

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';

`FeedXSLTOptions`

Permits to style the blog XML feeds so that browsers render them nicely with XSLT.

Use true to let the blog use its built-in .xsl and .css files to style the blog feed
Use a falsy value (undefined | null | false) to disable the feature
Use a string to provide a file path to a custom .xsl file relative to the blog content folder. By convention, you must provide a .css file with the exact same name.

type FeedXSLTOptions =
  | boolean
  | undefined
  | null
  | {
      rss?: string | boolean | null | undefined;
      atom?: string | boolean | null | undefined;
    };

`CreateFeedItemsFn`

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

`ProcessBlogPostsFn`

type ProcessBlogPostsFn = (params: {
  blogPosts: BlogPost[];
}) => Promise<void | BlogPost[]>;

Exemple de 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',
          // Cas simple : une chaine editUrl
          // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
          // Cas avancé : une fonction 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({
                // ne conserver que les 10 articles de blog les plus récents dans le flux
                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',
        // Cas simple : une chaine editUrl
        // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
        // Cas avancé : une fonction 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({
              // ne conserver que les 10 articles de blog les plus récents dans le flux
              blogPosts: blogPosts.filter((item, index) => index < 10),
              ...rest,
            });
          },
        },
      },
    ],
  ],
};

Markdown frontmatter

Les documents Markdown peuvent utiliser les champs de métadonnées Markdown du front matter suivants, entourés d'une ligne --- de part et d'autre.

Champs acceptés :

Nom	Type	Par défaut	Description
`authors`	`Authors`	`undefined`	Liste 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.
`author`	`string`	`undefined`	⚠️ Préférez l'utilisation de `authors`. Le nom de l'auteur de l'article du blog.
`author_url`	`string`	`undefined`	⚠️ Préférez l'utilisation de `authors`. L'URL à laquelle le nom de l'auteur sera lié. This could be a GitHub, X, Facebook profile URL, etc.
`author_image_url`	`string`	`undefined`	⚠️ Préférez l'utilisation de `authors`. L'URL de l'image miniature de l'auteur.
`author_title`	`string`	`undefined`	⚠️ Préférez l'utilisation de `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. 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.
`tags`	`Tag[]`	`undefined`	Une liste de chaînes ou d'objets de deux champs de chaînes `label` et `permalink` pour tagger à votre article. Strings can be a reference to keys of a tags file (usually `tags.yml`)
`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`	Balise meta des mots clés, qui deviendra le `<meta name="keywords" content="keyword1,keyword2,..."/>` dans `<head>`, utilisé par les moteurs de recherche.
`description`	`string`	La première ligne du contenu Markdown	La description de votre document, qui deviendra la `<meta name="description" content="..."/>` et `<meta property="og:description" content="..."/>` dans `<head>`, utilisé par les moteurs de recherche.
`image`	`string`	`undefined`	Image de couverture ou vignette qui sera utilisée comme `<meta property="og:image" content="..."/>` dans le `<head>`, améliorant les aperçus de liens sur les médias sociaux et les plateformes de messagerie.
`slug`	`string`	Chemin du fichier	Permet 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: `/`.
`last_update`	`FrontMatterLastUpdate`	`undefined`	Permet de remplacer l'auteur et/ou la date de la dernière mise à jour. La date peut être toute chaîne de date interprétable.

type FrontMatterLastUpdate = {date?: string; author?: string};

type Tag = string | {label: string; permalink: string};

// An author key references an author from the global plugin authors.yml file
type AuthorKey = string;

// Social platform name -> Social platform link
// Example: {MyPlatform: 'https://myplatform.com/myusername'}
// Pre-defined platforms ("x", "github", "twitter", "linkedin", "stackoverflow") accept handles:
// Example: {github: 'slorber'}
type AuthorSocials = Record<string, string>;

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

// The front matter authors field allows various possible shapes
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
    socials:
      x: joelmarcey
      github: JoelMarcey
tags: [docusaurus]
description: This is my first post on Docusaurus.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

Un article de blog Markdown

Tags File

Use the tags plugin option to configure the path of a YAML tags file.

By convention, the plugin will look for a tags.yml file at the root of your content folder(s).

This file can contain a list of predefined tags. You can reference these tags by their keys in Markdown files thanks to the tags front matter.

Keeping tags consistent

Using a tags file, you can ensure that your tags usage is consistent across your plugin content set. Use the onInlineTags: 'throw' plugin option to enforce this consistency and prevent usage of inline tags declared on the fly.

Types

The YAML content of the provided tags file should respect the following shape:

type Tag = {
  label?: string; // Tag display label
  permalink?: string; // Tag URL pathname segment
  description?: string; // Tag description displayed in the tag page
};

type TagsFileInput = Record<string, Partial<Tag> | null>;

Example

tags.yml
releases:
  label: 'Product releases'
  permalink: '/product-releases'
  description: 'Content related to product releases.'

# A partial tag definition is also valid
announcements:
  label: 'Announcements'

# An empty tag definition is also valid
# Other attributes will be inferred from the key
emptyTag:

content.md
---
tags: [releases, announcements, emptyTag]
---

# Title

Content

Authors File

Use the authors plugin option to configure the path of a YAML authors file.

By convention, the plugin will look for a authors.yml file at the root of your blog content folder(s).

This file can contain a list of predefined global blog authors. You can reference these authors by their keys in Markdown files thanks to the authors front matter.

Types

The YAML content of the provided authors file should respect the following shape:

type AuthorsMapInput = {
  [authorKey: string]: AuthorInput;
};

type AuthorInput = {
  name?: string;
  title?: string;
  description?: string;
  imageURL?: string;
  url?: string;
  email?: string;
  page?: boolean | {permalink: string};
  socials?: Record<string, string>;
  [customAuthorAttribute: string]: unknown;
};

Exemple

tags.yml
slorber:
  name: Sébastien Lorber
  title: Docusaurus maintainer
  url: https://sebastienlorber.com
  image_url: https://github.com/slorber.png
  page: true
  socials:
    x: sebastienlorber
    github: slorber

jmarcey:
  name: Joel Marcey
  title: Co-creator of Docusaurus 1
  url: https://github.com/JoelMarcey
  image_url: https://github.com/JoelMarcey.png
  email: jimarcey@gmail.com
  page:
    permalink: '/joel-marcey'
  socials:
    x: joelmarcey
    github: JoelMarcey

blog/my-blog-post.md
---
authors: [slorber, jmarcey]
---

# My Blog Post

Content

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 les options du plugin qui seront rendues
└── options.json

Installation​

Configuration​

Types​

EditUrlFn​

ReadingTimeFn​

FeedType​

FeedXSLTOptions​

CreateFeedItemsFn​

ProcessBlogPostsFn​

Exemple de configuration​

Markdown frontmatter​

Tags File​

Types​

Example​

Authors File​

Types​

Exemple​

i18n​

Emplacement des fichiers de traduction​

Exemple de structure du système de fichiers​

Installation

Configuration

Types

`EditUrlFn`

`ReadingTimeFn`

`FeedType`

`FeedXSLTOptions`

`CreateFeedItemsFn`

`ProcessBlogPostsFn`

Exemple de configuration

Markdown frontmatter

Tags File

Types

Example

Authors File

Types

Exemple

i18n

Emplacement des fichiers de traduction

Exemple de structure du système de fichiers