Blog
La fonction blog vous permet de déployer un blog complet en un rien de temps.
Consultez la documentation de référence de l'API du plugin du 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
:
export default {
themeConfig: {
// ...
navbar: {
items: [
// ...
{to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
],
},
},
};
Ajouter des articles
Pour publier dans le blog, créez un fichier Markdown dans le répertoire blog.
For example, create a file at website/blog/2019-09-05-hello-docusaurus.md
:
---
title: Welcome Docusaurus
description: This is my first post on Docusaurus.
slug: welcome-docusaurus-v2
authors:
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
- name: Sébastien Lorber
title: Docusaurus maintainer
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
---
Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).
<!-- truncate -->
This is my first post on Docusaurus 2.
A whole bunch of exploration to follow.
Le front matter 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 connaître tous les champs possibles, consultez la documentation de l'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 <!--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é. Notez que la partie située au-dessus du marqueur truncate doit être un texte Markdown autonome pouvant être rendu. Par exemple :
---
title: Markdown blog truncation example
---
All these will be part of the blog post summary.
<!-- truncate -->
But anything from here on down will not be.
For files using the .mdx
extension, use a MDX comment {/* truncate */}
instead:
---
title: MDX blog truncation Example
---
All these will be part of the blog post summary.
{/* truncate */}
But anything from here on down will not be.
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 s'afficheront en première page. Vous pouvez également ajouter une méta description à la page de la liste de blog pour un meilleur référencement :
export default {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogTitle: 'Docusaurus blog!',
blogDescription: 'A Docusaurus powered blog!',
postsPerPage: 'ALL',
},
},
],
],
};
Barre latérale du blog
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 « Articles récents », vous pourriez préférer afficher « Tous les articles » :
export default {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogSidebarTitle: 'Tous les articles',
blogSidebarCount: 'ALL',
},
},
],
],
};
Date de l'article du blog
Docusaurus will extract a YYYY-MM-DD
date from many patterns such as YYYY-MM-DD-my-blog-post-title.md
or YYYY/MM/DD/my-blog-post-title.md
. Cela vous permet de regrouper facilement les articles de blog par année, par mois, ou d'utiliser une structure plate.
Supported date extraction patterns
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 |
Docusaurus peut extraire la date des publications en utilisant n'importe quel modèle de nommage ci-dessus. Il est conseillé de choisir un modèle et de l'appliquer à tous les articles pour éviter toute confusion.
Utiliser 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 front matter. Puisque le front matter suit la syntaxe YAML où la notation de la date est prise en charge, vous pouvez utiliser le front matter si vous avez besoin de dates de publication plus précises. Par exemple, si vous avez plusieurs articles publiés le même jour, vous pouvez les trier selon l'heure de la journée :
---
date: 2021-09-13T10:00
---
---
date: 2021-09-13T18:00
---
Auteurs d'articles du blog
Utilisez le champ authors
du front matter 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 peuvent être déclarés directement à l'intérieur du front matter :
- Auteur unique
- Plusieurs auteurs
---
authors:
name: Joel Marcey
title: Co-créateur de Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
email: jimarcey@gmail.com
---
---
authors:
- name: Joel Marcey
title: Co-créateur de Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
email: jimarcey@gmail.com
- name: Sébastien Lorber
title: Mainteneur de Docusaurus
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
---
Cette option convient particulièrement pour commencer ou pour des auteurs occasionnels ou irréguliers.
Préférez l'utilisation de authors
du front matter, mais l'ancien author_*
du front matter reste pris en charge :
---
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, il peut être fastidieux de maintenir leurs informations dans chaque article du blog.
Il est possible de déclarer ces auteurs globalement dans un fichier de configuration :
jmarcey:
name: Joel Marcey
title: Co-créateur de Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
email: jimarcey@gmail.com
slorber:
name: Sébastien Lorber
title: Mainteneur de Docusaurus
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
Utilisez l'option du plugin authorsMapPath
pour configurer le chemin. Le format JSON est également pris en charge.
Dans le front matter des articles du blog, vous pouvez référencer les auteurs déclarés dans le fichier de configuration globale :
- Auteur unique
- Plusieurs auteurs
---
authors: jmarcey
---
---
authors: [jmarcey, slorber]
---
Le système authors
est très flexible et peut convenir à un cas d'utilisation plus avancé :
Mélanger 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 :
---
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
---
Remplacer localement les auteurs globaux
Vous pouvez personnaliser les données globales de l'auteur sur la base de chaque article du blog:
---
authors:
- key: jmarcey
title: Le nouveau titre de Joel Marcey
- key: slorber
name: Le nouveau nom de Sébastien Lorber
---
Localiser 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 de test pour en connaître l'effet.
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
Pour chaque article du blog, Docusaurus génère une estimation du temps de lecture, basé sur le nombre de mots. Une option permet de personnaliser cette fonctionnalité.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true, // When set to false, the "x min read" won't be shown
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 front matter 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
.
Utilisez le callback pour tous vos besoins de personnalisation :
- Désactivation par article
- Options de transmission
- Utilisation d'algorithmes personnalisés
Désactiver le temps de lecture sur une page :
export default {
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 :
export default {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
readingTime: ({content, defaultReadingTime}) =>
defaultReadingTime({content, options: {wordsPerMinute: 100}}),
},
},
],
],
};
Utiliser une implémentation personnalisée du temps de lecture :
import myReadingTime from './myReadingTime';
export default {
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; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
limit?: number | false | null; // defaults to 20
/** Permet le contrôle de la construction des BlogFeedItems */
createFeedItems?: (params: {
blogPosts: BlogPost[];
siteConfig: DocusaurusConfig;
outDir: string;
defaultCreateFeedItems: (params: {
blogPosts: BlogPost[];
siteConfig: DocusaurusConfig;
outDir: string;
}) => Promise<BlogFeedItem[]>;
}) => Promise<BlogFeedItem[]>;
};
};
Exemple d'utilisation :
export default {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
feedOptions: {
type: 'all',
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
createFeedItems: async (params) => {
const {blogPosts, defaultCreateFeedItems, ...rest} = params;
return defaultCreateFeedItems({
// keep only the 10 most recent blog posts in the feed
blogPosts: blogPosts.filter((item, index) => index < 10),
...rest,
});
},
},
},
},
],
],
};
Les flux peuvent être trouvés 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 exécuter votre site Docusaurus 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 example.com/
au lieu de la sous-route example.com/blog/
.
export default {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: false, // Optional: disable the docs plugin
blog: {
routeBasePath: '/', // Serve the blog at the site's root
/* other blog options */
},
},
],
],
};
N'oubliez pas de supprimer la page d'accueil existante à ./src/pages/index.js
sinon il y aura deux fichiers correspondant à la même route !
Il y a aussi un « mode Docs-uniquement » pour ceux qui ne veulent utiliser que les Docs. Lisez le Mode Docs uniquement pour des instructions détaillées ou une explication plus élaborée de routeBasePath
.
Blogs multiples
Par défaut, le thème classique ne supporte 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 cependant possible ! Vous pouvez ajouter un blog supplémentaire en spécifiant un autre plugin de blog via l'option plugins
dans docusaurus.config.js
.
Définissez routeBasePath
avec l'URL à laquelle vous souhaitez 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 d'accès ! Définissez aussi path
avec le chemin du répertoire contenant les entrées de votre second blog.
Comme décrit pour les plugins multi-instance, vous devez assigner un ID unique à chaque plugin.
export default {
// ...
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/**
* Required for any multi-instance plugin
*/
id: 'second-blog',
/**
* URL route for the blog section of your site.
* *DO NOT* include a trailing slash.
*/
routeBasePath: 'my-second-blog',
/**
* Path to data on filesystem relative to site dir.
*/
path: './my-second-blog',
},
],
],
};
À titre d'exemple, nous hébergeons un deuxième blog ici.