Version : 2.2.0

Blog

La fonction blog vous permet de déployer un blog complet en un rien de temps.

info

Consultez la documentation de référence de l'API du plugin Blog pour une liste exhaustive des options.

Configuration initiale

Pour configurer le blog de votre site, commencez par créer un répertoire blog.

Ensuite, ajoutez un lien vers le blog dans docusaurus.config.js :

docusaurus.config.js
module.exports = {
  themeConfig: {
    // ...
    navbar: {
      items: [
        // ...
        {to: 'blog', label: 'Blog', position: 'left'}, // ou position: 'right'
      ],
    },
  },
};

Ajouter des articles

Pour publier dans le blog, créez un fichier Markdown dans le répertoire blog.

Par exemple, créez un fichier à website/blog/2019-09-05-hello-docusaurus-v2.md :

website/blog/2019-09-05-hello-docusaurus-v2.md
---
title: Bienvenue Docusaurus v2
description: Ceci est mon premier article sur Docusaurus 2.
slug: welcome-docusaurus-v2
authors:
  - name: Joel Marcey
    title: Co-créateur de Docusaurus 1
    url: https://github.com/JoelMarcey
    image_url: https://github.com/JoelMarcey.png
  - name: Sébastien Lorber
    title: Mainteneur de Docusaurus
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
tags: [hello, docusaurus-v2]
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

Bienvenue sur ce blog. Ce blog est créé avec [**Docusaurus 2**](https://docusaurus.io/).

<!--truncate-->

C'est mon premier post sur Docusaurus 2.

Un tas d'exploration à suivre.

Le frontmatter est utile pour ajouter des métadonnées supplémentaires à votre article de blog, par exemple des informations sur l'auteur, mais Docusaurus sera capable de déduire toutes les métadonnées nécessaires sans le frontmatter. Pour tous les champs possibles, consultez la documentation API.

Liste du blog

La page d'index du blog (par défaut, elle se trouve dans /blog) est la page de présentation du blog, où tous les articles du blog sont affichés collectivement.

Utilisez le marqueur  dans votre article du blog pour représenter ce qui sera affiché comme résumé lors de l'affichage de tous les articles du blog publiés. Tout ce qui est au-dessus de  fera partie du résumé. Par exemple :

---
title: Exemple de résumé
---

Tout ceci fera partie du résumé de l'article du blog.

Même cela.

<!--truncate-->

Mais ce qui est ici ne le sera pas.

Pas ça.

Ni ceci.

Par défaut, 10 articles sont affichés sur chaque page de la liste du blog, mais vous pouvez contrôler la pagination avec l'option postsPerPage dans la configuration du plugin. Si vous définissez postsPerPage: 'ALL', la pagination sera désactivée et tous les articles seront affichés sur la première page. Vous pouvez également ajouter une méta description à la page de la liste de blog pour un meilleur référencement :

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          blogTitle: 'Blog de Docusaurus !',
          blogDescription: 'Un blog alimenté par Docusaurus !',
          postsPerPage: 'ALL',
        },
      },
    ],
  ],
};

La barre latérale du blog affiche les articles récents du blog. Le nombre d'éléments affichés par défaut est de 5, mais vous pouvez personnaliser avec l'option blogSidebarCount dans la configuration du plugin. En définissant blogSidebarCount: 0, la barre latérale sera complètement désactivée, le conteneur étant également supprimé. Cela augmentera la largeur du conteneur principal. En particulier, si vous avez défini blogSidebarCount: 'ALL', tous les articles seront affichés.

Vous pouvez également modifier le texte d'entête de la barre latérale avec l'option blogSidebarTitle. Par exemple, si vous avez défini blogSidebarCount : 'ALL', au lieu de l'affichage par défaut "Recent posts", vous préféreriez peut-être qu'il indique "All posts" :

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          blogSidebarTitle: 'Tous les articles',
          blogSidebarCount: 'ALL',
        },
      },
    ],
  ],
};

Date de l'article du blog

Docusaurus va extraire une date AAAA-MM-JJ à partir d'un nom de fichier/dossier tel que AAAA-MM-JJ-blog-post-title.md.

Exemple de modèles pris en charge

Modèle	Exemple
Fichier simple	`2021-05-28-my-blog-post-title.md`
Fichier MDX	`2021-05-28-my-blog-post-title.mdx`
Dossier simple + `index.md`	`2021-05-28-my-blog-post-title/index.md`
Dossier nommé par date	`2021-05-28/my-blog-post-title.md`
Dossiers imbriqués par date	`2021/05/28/my-blog-post-title.md`
Dossiers partiellement imbriqués par date	`2021/05-28-my-blog-post-title.md`
Dossiers imbriqués + `index.md`	`2021/05/28/my-blog-post-title/index.md`
Date au milieu du chemin	`category/2021/05-28-my-blog-post-title.md`

La date sera supprimée du chemin et ajoutée au début du slug de l'URL.

astuce

L'utilisation d'un dossier peut s'avérer pratique pour placer les images de l'article de blog au même endroit que le fichier Markdown.

Cette convention de nommage est facultative et vous pouvez fournir la date dans le frontmatter. Puisque le frontmatter suit la syntaxe YAML où la notation de la date est prise en charge, vous pouvez utiliser le frontmatter si vous avez besoin de dates de publication plus précises. Par exemple, si vous avez plusieurs messages publiés le même jour, vous pouvez les trier selon l'heure de la journée :

earlier-post.md
---
date: 2021-09-13T10:00
---

later-post.md
---
date: 2021-09-13T18:00
---

Auteurs d'articles du blog

Utilisez le champ authors du frontmatter pour déclarer les auteurs des articles du blog. Un auteur doit avoir au moins name ou image_url. Docusaurus utilise des informations comme url, email, et title, mais toute autre information est autorisée.

Auteurs en ligne

Les auteurs d'articles du blog peuvent être déclarés directement à l'intérieur du frontmatter :

Single author
Multiple authors

my-blog-post.md
---
authors:
  name: Joel Marcey
  title: Co-créateur de Docusaurus 1
  url: https://github.com/JoelMarcey
  image_url: https://github.com/JoelMarcey.png
  email: [email protected]
---

my-blog-post.md
---
authors:
  - name: Joel Marcey
    title: Co-créateur de Docusaurus 1
    url: https://github.com/JoelMarcey
    image_url: https://github.com/JoelMarcey.png
    email: [email protected]
  - name: Sébastien Lorber
    title: Mainteneur de Docusaurus
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
---

astuce

Cette option est la plus efficace pour débuter, ou pour les auteurs occasionnels et irréguliers.

info

Préférez l'utilisation de authors du frontMmatter, mais l'ancien author_* du frontmatter reste pris en charge :

my-blog-post.md
---
author: Joel Marcey
author_title: Co-créateur de Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://github.com/JoelMarcey.png
---

Auteurs globaux

Pour les auteurs réguliers du blog, il peut être fastidieux de maintenir les informations des auteurs dans chaque article du blog.

Il est possible de déclarer ces auteurs globalement dans un fichier de configuration :

website/blog/authors.yml
jmarcey:
  name: Joel Marcey
  title: Co-créateur de Docusaurus 1
  url: https://github.com/JoelMarcey
  image_url: https://github.com/JoelMarcey.png
  email: [email protected]

slorber:
  name: Sébastien Lorber
  title: Mainteneur de Docusaurus
  url: https://sebastienlorber.com
  image_url: https://github.com/slorber.png

astuce

Utilisez l'option du plugin authorsMapPath pour configurer le chemin. Le JSON est également pris en charge.

Dans le frontmatter des articles du blog, vous pouvez référencer les auteurs déclarés dans le fichier de configuration globale :

Single author
Multiple authors

my-blog-post.md
---
authors: jmarcey
---

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

info

Le système authors est très flexible et peut convenir à un cas d'utilisation plus avancé :

Mélangez les auteurs en ligne et les auteurs globaux

Vous pouvez utiliser les auteurs globaux la plupart du temps, et toujours utiliser les auteurs en ligne :

my-blog-post.md
---
authors:
  - jmarcey
  - slorber
  - name: Nom de l'auteur en ligne
    title: Titre de l'auteur en ligne
    url: https://github.com/inlineAuthor
    image_url: https://github.com/inlineAuthor
---

Remplacement local des auteurs globaux

Vous pouvez personnaliser les données globales de l'auteur sur la base de chaque article du blog:

my-blog-post.md
---
authors:
  - key: jmarcey
    title: Le nouveau titre de Joel Marcey
  - key: slorber
    name: Le nouveau nom de Sébastien Lorber
---

Traduisez le fichier de configuration de l'auteur

Le fichier de configuration peut être traduit, il suffit d'en créer une copie traduite à cet endroit :

website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml

Un auteur, qu'il soit déclaré par le front matter ou par la carte des auteurs, doit avoir un nom ou un avatar, ou les deux. Si tous les auteurs d'un message n'ont pas de noms, Docusaurus affichera leurs avatars de manière compacte. Consultez cet article test pour voir l'effet.

génération de flux

Les flux RSS nécessitent que l'email de l'auteur soit défini pour que l'auteur apparaisse dans le flux.

Temps de lecture

Docusaurus génère une estimation du temps de lecture pour chaque article du blog basé sur le nombre de mots. Nous fournissons une option pour personnaliser cela.

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          showReadingTime: true, // S'il est défini à false, le "x min read" ne sera pas affiché.
          readingTime: ({content, frontMatter, defaultReadingTime}) =>
            defaultReadingTime({content, options: {wordsPerMinute: 300}}),
        },
      },
    ],
  ],
};

Le callback readingTime reçoit trois paramètres : le texte du contenu du blog sous forme de chaîne de caractères, le frontmatter sous forme d'un enregistrement de clés de chaîne de caractères et de leurs valeurs, et la fonction de temps de lecture par défaut. Il renvoie un nombre (temps de lecture en minutes) ou undefined (pour désactiver le temps de lecture pour cette page).

Le temps de lecture par défaut est capable d'accepter des options supplémentaires : wordsPerMinute comme un nombre (par défaut : 300) et wordBound comme une fonction qui transforme une chaîne de caractères en booléen. Si la chaîne passée à wordBound doit être un mot lié (espaces, tabulations et sauts de ligne par défaut), la fonction doit retourner true.

astuce

Utilisez le callback pour tous vos besoins de personnalisation :

Per-post disabling
Passing options
Using custom algorithms

Désactiver le temps de lecture sur une page :

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          showReadingTime: true,
          readingTime: ({content, frontMatter, defaultReadingTime}) =>
            frontMatter.hide_reading_time
              ? undefined
              : defaultReadingTime({content}),
        },
      },
    ],
  ],
};

Utilisation :

---
hide_reading_time: true
---

Cette page n'affichera plus les stats de temps de lecture !

Passer les options à la fonction de temps de lecture par défaut :

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content, defaultReadingTime}) =>
            defaultReadingTime({content, options: {wordsPerMinute: 100}}),
        },
      },
    ],
  ],
};

Utiliser une implémentation personnalisée du temps de lecture :

docusaurus.config.js
const myReadingTime = require('./myReadingTime');

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content}) => myReadingTime(content),
        },
      },
    ],
  ],
};

Flux

Vous pouvez générer des flux RSS / Atom /JSON en passant feedOptions. Par défaut, les flux RSS et Atom sont générés. Pour désactiver la génération de flux, définissez feedOptions.type à null.

type FeedType = 'rss' | 'atom' | 'json';

type BlogOptions = {
  feedOptions?: {
    type?: FeedType | 'all' | FeedType[] | null;
    title?: string;
    description?: string;
    copyright: string;
    language?: string; // valeurs possibles : http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
  };
};

Exemple d'utilisation:

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          feedOptions: {
            type: 'all',
            copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
          },
        },
      },
    ],
  ],
};

Le flux peut être trouvé sur :

RSS
Atom
JSON

https://example.com/blog/rss.xml

https://example.com/blog/atom.xml

https://example.com/blog/feed.json

Fonctionnalités avancées

Mode blog-uniquement

Vous pouvez faire fonctionner votre site Docusaurus 2 sans page d'accueil dédiée et utiliser la liste des articles de votre blog comme page d'index. Définissez routeBasePath comme étant '/' pour servir le blog via la route racine exemple.com/ au lieu de la sous-route exemple.com/blog/.

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: false, // Facultatif : désactive le plugin docs
        blog: {
          routeBasePath: '/', // Sert le blog à la racine du site
          /* autres options du blog */
        },
      },
    ],
  ],
};

attention

N'oubliez pas de supprimer la page d'accueil existante à ./src/pages/index.js sinon il y aura deux fichiers qui correspondent à la même route !

astuce

Il y a aussi un « mode Docs-uniquement » pour ceux qui ne veulent utiliser que les Docs. Lisez Mode Docs-uniquement pour des instructions détaillées ou une explication plus élaborée de routeBasePath.

Plusieurs blogs

Par défaut, le thème classic n'assume qu'un seul blog par site et n'inclut donc qu'une seule instance du plugin blog. Si vous souhaitez avoir plusieurs blogs sur un seul site web, c'est aussi possible ! Vous pouvez ajouter un autre blog en spécifiant un autre plugin de blog dans l'option plugins dans docusaurus.config.js.

Définissez routeBasePath avec l'URL sur laquelle vous voulez que votre deuxième blog soit accessible. Notez que routeBasePath doit être différent du premier blog sinon il pourrait y avoir une collision de chemins ! Aussi, définissez path avec le chemin du répertoire contenant les entrées de votre second blog.

Comme décrits dans les plugins multi-instance, vous devez assigner un ID unique aux plugins.

docusaurus.config.js
module.exports = {
  // ...
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        /**
         * Requis pour tout plugin multi-instance
         */
        id : 'second-blog',
        /**
         * URL pour la section blog de votre site.
         * * * NE PAS inclure de slash.
         */
        routeBasePath: 'my-second-blog',
        /**
         * Chemin vers les données sur le système de fichiers relatif au répertoire du site.
         */
        path: './my-second-blog',
      },
    ],
  ],
};

À titre d'exemple, un second blog est hébergé ici.

Blog

Configuration initiale​

Ajouter des articles​

Liste du blog​

Barre latérale du blog​

Date de l'article du blog​

Auteurs d'articles du blog​

Auteurs en ligne​

Auteurs globaux​

Temps de lecture​

Flux​

Fonctionnalités avancées​

Mode blog-uniquement​

Plusieurs blogs​

Configuration initiale

Ajouter des articles

Liste du blog

Barre latérale du blog

Date de l'article du blog

Auteurs d'articles du blog

Auteurs en ligne

Auteurs globaux

Temps de lecture

Flux

Fonctionnalités avancées

Mode blog-uniquement

Plusieurs blogs