Version: 2.0.0-beta.9

📦 plugin-content-blog

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

Installation

npm
Yarn

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

yarn add @docusaurus/plugin-content-blog

tip

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`	!!crwdBlockTags_267_sgaTkcolBdwrc!!	`undefined`	URL de base pour modifier votre site. L'URL finale est calculée par `editUrl + relativeDocPath`. 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`	!!crwdBlockTags_268_sgaTkcolBdwrc!!	`5`	Nombre d'éléments à afficher dans la barre latérale du blog. `'ALL'` pour afficher tous les articles du blog; `0` pour désactiver
`blogSidebarTitle`	`string`	`'Recent posts'`	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 page de la liste des tags de votre site. Il est préfixé par `routeBasePath`.
`archiveBasePath`	`string`	`'/archive'`	Route URL pour la section archive du blog de votre site. Il est préfixé par `routeBasePath`. NE PAS inclure un slash de fin.
`include`	`string[]`	`['*/.{md,mdx}']`	Les fichiers correspondants seront inclus et traités.
`exclude`	`string[]`	Voir l'exemple de configuration	Aucune route ne sera créée pour les fichiers correspondants.
`postsPerPage`	!!crwdBlockTags_269_sgaTkcolBdwrc!!	`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".
`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`	`string`	`/<!--\s(truncate)\s-->/`	Truncate marker, peut être un regex ou une chaîne.
`showReadingTime`	`boolean`	`true`	Affiche le temps de lecture estimé pour l'article du blog.
`readingTime`	`ReadingTimeFunctionOption`	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 spécifié avec `path`. Peut également être un fichier `json`.
`feedOptions`	Voir ci-dessous	`{type: ['rss', 'atom']}`	Flux du blog. Si undefined, aucun flux rss ne sera généré.
`feedOptions.type`	!!crwdBlockTags_270_sgaTkcolBdwrc!! (ou tableau d'options multiples)	Obligatoire	Type de flux à générer.
`feedOptions.title`	`string`	`siteConfig.title`	Titre du flux.
`feedOptions.description`	`string`	!!crwdBlockTags_271_sgaTkcolBdwrc!!	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.

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

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

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

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

Exemple de configuration

Voici un exemple d'objet de configuration.

Vous pouvez le fournir en tant qu'options du preset ou options du plugin.

tip

La plupart des utilisateurs de Docusaurus configurent ce plugin via les options du preset.

const config = {
  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}) => {
    return `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 preset

Si vous utilisez un preset, configurez ce plugin à travers les options du preset :

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          path: 'blog',
          // ... objet de configuration ici
        },
      },
    ],
  ],
};

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',
        // ... objet de configuration ici
      },
    ],
  ],
};

Markdown Frontmatter

Les documents Markdown peuvent utiliser les champs de métadonnées Markdown 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 et ne doit donc pas encore être publié. Cependant, les brouillons du blog seront affichés pendant le 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`	Keywords meta tag, which will become the `<meta name="keywords" content="keyword1,keyword2,..."/>` in `<head>`, used by search engines.
`description`	`string`	The first line of Markdown content	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`	File path	Allows to customize the blog post url (`/<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};

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

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

// The FrontMatter authors field allows various possible shapes
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

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
│
│ # translations for website/blog
├── authors.yml
├── first-blog-post.md
├── second-blog-post.md
│
│ # translations for the plugin options that will be rendered
└── options.json

Installation​

tip

Configuration​

Exemple de configuration​

tip

Options du preset​

Options du plugin​

Markdown Frontmatter​

i18n​

Emplacement des fichiers de traduction​

Exemple de structure du système de fichiers​

Installation

Configuration

Exemple de configuration

Options du preset

Options du plugin

Markdown Frontmatter

i18n

Emplacement des fichiers de traduction

Exemple de structure du système de fichiers