Aller au contenu
DevSecOps Logo DevSecOps Logo DevSecOps
Docs
Blog
Blog

Installation du plugin Starlight Blog

Mise à jour :

logo astro

Disposer d’une section blog peut s’avérer extrêmement précieux pour partager des mises à jour, des tutoriels, ou des réflexions plus approfondies avec votre audience. Astro Starlight, un thème conçu spécifiquement pour les sites de documentation, offre désormais la possibilité d’intégrer un blog grâce à un plugin dédié.

Que vous souhaitiez informer vos utilisateurs des dernières fonctionnalités ou partager des conseils pratiques, l’ajout d’un blog à votre documentation peut enrichir l’expérience utilisateur et renforcer la valeur de votre contenu. Ce guide s’adresse à tous ceux qui utilisent déjà Astro Starlight ou envisagent de le faire, et qui souhaitent ajouter une dimension supplémentaire à leur site de documentation en y intégrant un blog. Nous aborderons ensemble les différentes étapes, de l’installation initiale à la configuration avancée, pour que vous puissiez mettre en ligne votre premier article dans les meilleures conditions.

Ce guide a pour objectif de vous accompagner pas à pas dans l’installation et la configuration de ce plugin, afin de vous permettre de tirer pleinement parti de cette fonctionnalité sur votre site.

Fonctionnalités du Plugin Blog

Le plugin blog pour Astro Starlight propose une série de fonctionnalités robustes qui vous permettent d’enrichir votre site de documentation avec un blog complet et dynamique. Voici les principales fonctionnalités offertes par ce plugin :

  • Liste des articles avec pagination : Affichage des articles avec une pagination intégrée, facilitant la navigation dans des blogs contenant de nombreux articles.
  • Gestion des auteurs : Possibilité de définir des auteurs globaux pour l’ensemble du site ou de spécifier des auteurs individuels pour chaque article.
  • Système de tags : Classification des articles par tags, permettant une organisation flexible et une navigation simplifiée pour les utilisateurs.
  • Images de couverture : Support des images de couverture pour chaque article, ajoutant un aspect visuel attrayant à votre blog.
  • Barre latérale personnalisable : Affichage des articles récents, tags populaires ou autres contenus, avec la possibilité de personnaliser complètement la barre latérale en fonction de vos besoins.
  • Flux RSS automatique : Génération automatique d’un flux RSS pour permettre aux lecteurs de s’abonner et de suivre les dernières publications.
  • Compatibilité avec Markdown, Markdoc, et MDX : Support des différents formats de contenu pour une flexibilité maximale dans la création et la structure des articles.
  • Internationalisation (i18n) : Gestion multilingue avec la possibilité de configurer des traductions et des labels spécifiques pour chaque langue supportée sur votre site.

Installation du plugin de Blog Starlight

Si vous avez déjà un site de documentation existant créé avec le template Starlight d’Astro, vous pouvez facilement y ajouter le plugin blog pour enrichir votre site avec une section blog. Voici les étapes détaillées pour l’installation et la configuration du plugin sur un projet existant. Pour les autres vous pouvez vous rendre sur mon précédent guide.

Avant de commencer, assurez-vous que votre projet est bien configuré avec Starlight. Vous devriez avoir un fichier astro.config.mjs où Starlight est déjà intégré en tant que plugin principal. Si ce n’est pas le cas, voici comment vérifier :

Ouvrez votre fichier astro.config.mjs et assurez-vous que Starlight est bien inclus dans les intégrations. Le fichier devrait ressembler à ceci :

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      social: {
        github: 'https://github.com/withastro/starlight',
      },
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    }),
  ],
});

Une fois votre projet préparé, vous pouvez procéder à l’installation du plugin blog :

  1. Ajouter l’intégration Starlight Blog : Dans le répertoire racine de votre projet, exécutez la commande suivante pour installer le plugin blog et l’ajouter aux intégrations de Starlight :

    Terminal window
    npm i starlight-blog

  2. Modifier la configuration : Après avoir installé le plugin, modifiez votre fichier astro.config.mjs pour y inclure le plugin blog. Voici un exemple de configuration :

    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    import starlightBlog from "starlight-blog";
    

    

    // https://astro.build/config
    export default defineConfig({
      integrations: [
        starlight({
          plugins: [
            starlightBlog({
              authors: {
                Bob: {
                  name: "Stéphane ROBERT",
                  title: "Architecte Cloud",
                  url: "https://github.com/stephrobert",
                  picture: "https://github.com/stephrobert.png",
                },
              },
              postCount: 12,
              frontmatter: {
                prev: false,
                next: false,
              },
            }),
          ],
          title: "My Docs",
          social: {
            github: "https://github.com/withastro/starlight",
          },
          defaultLocale: "root",
          pagination: true,
          // optional
          locales: {
            root: {
              label: "French",
              lang: "fr-FR", // lang is required for root locales
            },
          },
          sidebar: [
            {
              label: "Guides",
              items: [
                // Each item here is one entry in the navigation menu.
                { label: "Example Guide", slug: "guides/example" },
              ],
            },
            {
              label: "Reference",
              autogenerate: { directory: "reference" },
            },
          ],
        }),
      ],
    });

Pour gérer vos articles de blog, vous devez configurer les collections de contenu dans votre projet :

  1. Créer ou modifier le fichier de configuration : Dans le répertoire src/content/, créez ou modifiez le fichier config.ts pour définir la collection de contenu utilisée pour les articles de blog.

    import { defineCollection } from 'astro:content';
    import { docsSchema } from '@astrojs/starlight/schema';
    import { blogSchema } from 'starlight-blog/schema'
    

    export const collections = {
      docs: defineCollection({
        schema: docsSchema({
          extend: (context) => blogSchema(context)
        })
      }),
    };

  2. Créer le répertoire des articles : Dans le répertoire src/content/, créez un dossier nommé blog. C’est ici que vous ajouterez vos articles en format Markdown (.md) ou MDX (.mdx).

    Terminal window
    mkdir src/content/docs/blog

Ajouter des Articles de Blog

Une fois le plugin configuré, vous pouvez commencer à créer des articles pour votre blog :

  1. Créer un fichier Markdown pour un article : Ajoutez un nouveau fichier .md ou .mdx dans le répertoire src/content/docs/blog/. Par exemple :

    ---
    title: "Mon premier article"
    description: "Introduction au blog avec Astro Starlight"
    date: "2024-08-24"
    tags: ["Astro", "Starlight", "Blog"]
    cover:
      alt: A beautiful cover image
      image: ../../../assets/houston.webp
    ---
    

    Bienvenue sur mon premier article de blog utilisant le plugin Starlight.

  2. Utiliser les fonctionnalités du blog : Profitez des fonctionnalités comme les tags, les images de couverture, et la pagination pour structurer vos articles de manière optimale.

Tester et Déployer

Après avoir configuré et ajouté des articles, vous pouvez tester localement votre site pour vérifier que tout fonctionne comme prévu :

  1. Lancer le serveur de développement : Dans votre terminal, exécutez la commande suivante pour lancer le serveur de développement Astro :

    Terminal window
    npm run build
    npm run preview

alt text

  1. Vérifier le blog : Accédez à votre site via l’URL locale fournie par Astro et vérifiez que la section blog est bien fonctionnelle.

Explication sur la config

Cette configuration Astro définit les paramètres de votre site en utilisant plusieurs intégrations, dont Starlight et le plugin Starlight Blog. Voici une explication détaillée des différents éléments de ce fichier :

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightBlog from "starlight-blog";

Ces lignes importent les modules nécessaires pour configurer Astro. defineConfig est une fonction fournie par Astro pour définir les configurations. starlight est une intégration Astro dédiée aux sites de documentation, et starlightBlog est un plugin spécifique pour ajouter des fonctionnalités de blog à votre site.

integrations: [
  starlight({
    plugins: [
      starlightBlog({
        authors: {
          Bob: {
            name: "Stéphane ROBERT",
            title: "Architecte Cloud",
            url: "https://github.com/stephrobert",
            picture: "https://github.com/stephrobert.png",
          },
        },
        postCount: 12,
        frontmatter: {
          prev: false,
          next: false,
        },
      }),
    ],
    title: "My Docs",
    social: {
      github: "https://github.com/withastro/starlight",
    },
    sidebar: [
      {
        label: "Guides",
        items: [
          { label: "Example Guide", slug: "guides/example" },
        ],
      },
      {
        label: "Reference",
        autogenerate: { directory: "reference" },
      },
    ],
  }),
],

  • Plugin Starlight Blog

    • plugins : Ici, le plugin starlightBlog est utilisé pour ajouter des fonctionnalités de blog. Il est configuré avec des auteurs, un compteur de posts, et des paramètres de frontmatter.

      • authors : Définit les auteurs des articles de blog. Dans cet exemple, un auteur nommé “Bob” est défini, avec des informations telles que le nom, le titre, l’URL GitHub, et l’image de profil.

      • postCount : Ce paramètre spécifie le nombre d’articles à afficher. Ici, il est réglé à 12.

      • frontmatter : Ce bloc permet de désactiver les liens de navigation “prev” (précédent) et “next” (suivant) dans les articles de blog.

Explications sur le contenu de l’entête des fichiers markdown de la section blog

Dans un fichier Markdown utilisé pour un blog avec Astro Starlight, les champs frontmatter définis au début du fichier permettent de configurer différentes options pour l’article. Voici une explication détaillée de chaque champ dans l’exemple donné :

title

Le champ title définit le titre de l’article. Ce titre sera généralement affiché en haut de l’article et dans les listes d’articles (comme sur la page d’accueil du blog ou dans les pages de catégories).

Exemple dans votre fichier :

title: "Mon premier article"

excerpt

Le champ excerpt (ou extrait en français) est un court résumé de l’article. Il est souvent utilisé pour donner aux lecteurs un aperçu rapide du contenu de l’article. Cet extrait peut être affiché sur les pages de liste d’articles ou dans les résultats de recherche.

Exemple dans votre fichier :

excerpt: "Introduction au blog avec Astro Starlight"

date

Le champ date indique la date de publication de l’article. Ce champ est important pour organiser les articles par date et pour afficher des informations temporelles sur l’article. Le format est généralement YYYY-MM-DD.

Exemple dans votre fichier :

date: 2024-08-15

lastUpdated

Le champ lastUpdated est utilisé pour noter la dernière date de mise à jour de l’article. Cela permet aux lecteurs de savoir quand l’article a été mis à jour pour la dernière fois, ce qui est utile pour du contenu susceptible d’évoluer.

Exemple dans votre fichier :

lastUpdated: 2024-08-19

tags

Le champ tags contient une liste de mots-clés ou étiquettes associées à l’article. Ces tags aident à catégoriser le contenu et à faciliter la recherche et la navigation des utilisateurs à travers le site. Les articles peuvent être regroupés ou filtrés en fonction de ces tags.

Exemple dans votre fichier :

tags: ["Astro", "Starlight", "Blog"]

cover

Le champ cover permet de définir une image de couverture pour l’article. Ce champ est généralement un objet qui inclut plusieurs propriétés, telles que l’URL de l’image et une description alternative pour l’accessibilité (alt).

  • alt : Texte alternatif pour l’image, utilisé pour les lecteurs d’écran et affiché si l’image ne peut pas être chargée.
  • image : Chemin relatif vers l’image de couverture.

Exemple dans votre fichier :

cover:
  alt: A beautiful cover image
  image: ../../../assets/houston.webp

authors

Le champ authors permet de lister les auteurs de l’article. Il peut contenir un ou plusieurs noms d’auteurs, ce qui est utile pour attribuer correctement le contenu. C’est souvent un tableau, permettant de spécifier plusieurs contributeurs.

Exemple dans votre fichier :

authors:
  - Bob

Le champ featured est un booléen qui indique si l’article est mis en avant sur le site. Lorsqu’il est défini sur true, l’article peut apparaître dans des sections spéciales comme “Articles en vedette” sur la page d’accueil ou ailleurs sur le site.

Exemple dans votre fichier :

featured: true

draft

Le champ draft est un booléen qui indique si l’article est en brouillon. Si ce champ est défini sur true, l’article ne sera pas visible sur le site public. C’est utile pour travailler sur des articles non finalisés.

Exemple dans votre fichier :

draft: false

Contenu de l’Article

Le reste du fichier après le frontmatter est le contenu principal de l’article. Il est écrit en Markdown et sera transformé en HTML par le système lors du rendu de la page.

Exemple dans votre fichier :

Bienvenue sur mon premier article de blog utilisant le plugin Starlight.

Si vous ne connaissez pas le markdown, je vous invite à lire mon guide.

Configuration du Sitemap et du Flux RSS

Lors de la création d’une infrastructure web, il est important d’optimiser votre site pour le référencement (SEO) et de permettre aux utilisateurs de s’abonner à votre contenu via un flux RSS.

Un sitemap est un fichier XML qui liste toutes les URLs de votre site et fournit des informations sur chaque URL, comme la date de dernière modification et la fréquence de changement. Cela aide les moteurs de recherche à indexer votre site plus efficacement.

Le flux RSS permet aux utilisateurs de s’abonner à votre contenu et de recevoir des mises à jour directement dans leur lecteur RSS préféré.

Astro fournit une intégration simple pour générer automatiquement un sitemap.

  1. Ajouter l’intégration du sitemap :

    Commencez par installer l’intégration @astrojs/sitemap si ce n’est pas déjà fait :

    Terminal window
    npm install @astrojs/sitemap

  2. Configurer l’intégration dans astro.config.mjs :

    Ajoutez le module sitemap à la configuration de votre projet :

    import { defineConfig } from 'astro/config';
    import sitemap from '@astrojs/sitemap';
    

    export default defineConfig({
      site: 'https://votre-site.com',
      integrations: [sitemap()],
    });

    Cette configuration générera automatiquement un fichier sitemap.xml à la racine de votre site après chaque déploiement et le flux rss.

  3. Lancer la construction du site

Terminal window
npm run build
  1. **Vérifier la présence des fichiers dans le dossier dist :
  • sitemap-0.xml
  • sitemap-index.xml
  • blog/rss.xml
  1. Afficher le contenu du site :
Terminal window
npm run preview

Vous devriez voir apparaître le symbole du flux rss dans la barre de navigation.

Conclusion

En suivant ce guide, vous avez appris à installer et configurer le plugin blog sur un site existant créé avec le template Starlight d’Astro. Ce processus vous a permis d’ajouter une fonctionnalité de blog complète à votre site de documentation, enrichissant ainsi le contenu que vous pouvez offrir à vos utilisateurs.

Nous verrons bientôt les possibilités offertes par Astro et Starlight pour adapter notre site à nos besoins spécifiques et à ceux de notre audience.

Plus d’infos