Aller au contenu principal
Version: 2.0.0-beta.5 🚧

Blog

The blog feature enables you to deploy in no time a full-featured blog.

info

Check the Blog Plugin API Reference documentation for an exhaustive list of 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#

To publish in the blog, create a Markdown file within the blog directory.

For example, create a file at 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.
remarque

Docusaurus will extract a YYYY-MM-DD date from a file/folder name such as YYYY-MM-DD-my-blog-post-title.md.

This naming convention is optional, and you can provide the date as FrontMatter.

Example supported patterns
  • 2021-05-28-my-blog-post-title.md
  • 2021-05-28-my-blog-post-title.mdx
  • 2021-05-28-my-blog-post-title/index.md
  • 2021-05-28/my-blog-post-title.md
  • 2021/05/28/my-blog-post-title.md
  • 2021/05-28-my-blog-post-title.md
  • 2021/05/28/my-blog-post-title/index.md
  • ...
astuce

Using a folder can be convenient to co-locate blog post images alongside the Markdown file.

The only required field in the front matter is title; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see the API documentation.

Blog list#

The blog's index page (by default, it is at /blog) is the blog list page, where all blog posts are collectively displayed.

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.

By default, 10 posts are shown on each blog list page, but you can control pagination with the postsPerPage option in the plugin configuration. If you set postsPerPage: 'ALL', pagination will be disabled and all posts will be displayed on the first 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: 'Docusaurus blog!',          blogDescription: 'A Docusaurus powered blog!',          postsPerPage: 'ALL',        },      },    ],  ],};

Blog sidebar#

The blog sidebar displays recent blog posts. The default number of items shown is 5, but you can customize with the blogSidebarCount option in the plugin configuration. By setting blogSidebarCount: 0, the sidebar will be completely disabled, with the container removed as well. This will increase the width of the main container. Specially, if you have set blogSidebarCount: 'ALL', all posts will be displayed.

You can also alter the sidebar heading text with the blogSidebarTitle option. For example, if you have set blogSidebarCount: 'ALL', instead of the default "Recent posts", you may would rather make it say "All posts":

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

Because the sidebar title is hard-coded in the configuration file, it is currently untranslatable.

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.

type BlogOptions = {  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 !

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.