📦 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

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

Yarn

yarn 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'éléments à 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. NE PAS inclure un slash de fin.
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.
include	string[]	['**/*.{md,mdx}']	Tableau de patterns de glob correspondant aux fichiers Markdown à construire, par rapport 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.
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	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.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 (Voir 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.

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

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

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 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}) =>
            `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 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',
        // 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}) =>
          `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,
        },
      },
    ],
  ],
};

Markdown frontmatter

Les documents Markdown peuvent utiliser les champs de métadonnées Markdown du frontmatter suivants, entourés par une ligne --- de chaque côté.

Champs acceptés :

Nom	Type	Par défaut	Description
authors	Auteurs	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é. Il peut s'agir de l'URL d'un profil GitHub, Twitter, Facebook, 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	Markdown title	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îne label et permalink pour taguer votre article.
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 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_level	number	3	Le niveau maximum de titre 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 de 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	Couverture ou image miniature qui sera utilisée lors de l'affichage du lien vers votre article.
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: /.

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 :

---
titre: Bienvenue Docusaurus v2
authors:
  - slorber
  - yangshun
  - name: Joel Marcey
    title: Co-créateur de Docusaurus 1
    url: https://github. om/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 de blog Markdown

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