Aller au contenu principal
Version: 2.0.0-beta.4

Blog

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 dans le dossier du blog avec un nom au format AAAA-MM-JJ-Titre-de-mon-article.md. La date de publication est extraite du nom du fichier.

Par exemple, dans my-website/blog/2019-09-05-hello-docusaurus-v2.md :

---title: Bienvenue à Docusaurus v2author: Joel Marceyauthor_title: Co-créateur de Docusaurus 1author_url: https://github.com/JoelMarceyauthor_image_url: https://graph.facebook.com/611217057/picture/?height=200&width=200tags: [hello, docusaurus-v2]description: Ceci est mon premier post sur Docusaurus 2.image: https://i.imgur.com/mErPwqL.pnghide_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.

Options d'entête#

Le seul champ obligatoire est title ; toutefois, nous proposons des options permettant d'ajouter des informations sur l'auteur à votre article de blog, ainsi que d'autres options.

  • author : le nom de l'auteur à afficher.
  • author_url : 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 : l'URL de l'image miniature de l'auteur.
  • author_title : une description de l'auteur.
  • title : le titre de l'article du blog.
  • slug : 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: /.
  • date : la date de création de l'article du blog. Si non spécifié, cela pourrait être extrait du nom du fichier, par exemple 2021-04-15-blog-post.mdx. Par défaut, c'est l'heure de création du fichier Markdown.
  • tags : une liste de chaînes ou d'objets de deux champs de chaînes label et permalink pour tagger à votre article.
  • draft : 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.
  • description : La description de votre article qui sera fournit dans <meta name="description" content="..."/> et <meta property="og:description" content="..."/> du <head>, utilisés par les moteurs de recherche. Si ce champ n'est pas présent, il reprendra par défaut la première ligne du contenu.
  • keywords : méta-tag de mots-clés, qui deviendront les <meta name="keywords" content="keyword1,keyword2,..."/> dans le <head>, utilisés par les moteurs de recherche.
  • image : Image de couverture ou vignette qui sera utilisée lors de l'affichage du lien vers votre article.
  • hide_table_of_content : S'il faut cacher la table des matières à droite. Par défaut, c'est false.

Résumé de l'article#

Utilisez le marqueur <!--truncate--> 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 <!--truncate--> 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.

Flux#

Vous pouvez générer des flux RSS/Atom en passant les options de 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.

feedOptions?: {  type?: 'rss' | 'atom' | 'all' | null;  title?: string;  description?: string;  copyright: string;  language?: string; // possible values: 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.`,          },        },      },    ],  ],};

Accès au flux :

Le flux RSS peut être trouvé sur :

https://{your-domain}/blog/rss.xml

et pour Atom :

https://{your-domain}/blog/atom.xml

Fonctionnalités avancées#

Mode blog-uniquement#

Vous pouvez faire fonctionner votre site Docusaurus 2 sans page d'accueil et utiliser la liste des articles de votre blog comme page d'index. Définissez routeBasePath à '/' pour indiquer que c'est le chemin racine.

docusaurus.config.js
module.exports = {  // ...  presets: [    [      '@docusaurus/preset-classic',      {        docs: false,        blog: {          path: './blog',          routeBasePath: '/', // Définit cette valeur à '/'.        },      },    ],  ],};
caution

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 !

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: 'Docusaurus blog !',          blogDescription: 'Un blog propulsé par Docusaurus !',        },      },    ],  ],};

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.