Publier une documentation avec Astro Starlight

J’ai mis longtemps à vouloir mettre la main dans la pâte. Je m’explique, je contribue activement à la documentation d’Astro depuis plus d’un an.

Nous sommes entre 5-10 personnes si ce n’est pas plus à vous proposer du texte entièrement en français. Nous le faisons bénévolement sur notre temps libre, ça m’aide d’une part à apprendre un peu plus chaque jour l’anglais, et puis je me renseigne en quelque sorte sur Astro. Sans compter que ça favorise la communauté et l’entraide si besoin autour de ce framework. Bref, dans l’Open Source, nous ne sommes jamais seuls. Mais il faut savoir, qu’en un an de contributions, je n’ai JAMAIS touché à Astro. Même pas pour un simple projet ou le tester et voir comment il marche.

Aujourd’hui encore, je ne le connais pas assez comme je le devrais. Je me sens en quelque sorte comme un imposteur. Mais pour y remédier, j’ai créé la documentation de Mr. Robøt avec Astro Starlight !

Présentation d’Astro Starlight

On va faire étape par étape, avant de s’attaquer à Starlight, on va parler d’Astro.
Astro est un framework pour créer un site web axé sur un contenu. Que ça soit pour un blog personnel, de l'e-commerce et du marketing, ce ne sont que des exemples parmi d’autres.

Il est basé sur une architecture frontend, avec son frontmatter, et sa capacité à ne pas avoir de JavaScript. Oui oui, vous avez bien lu. Zéro JavaScript côté client. C’est de ça que vient la rapidité d’Astro, et qui vous donne un score de 100 points à toutes les catégories de Ligthouse !

Le résultat du test Lighthouse sur la page docs.mrrobot.app. On remarque que les quatre scores (performance, accessibilité, meilleures pratiques, SEO) sont à 100/100.

Vous avez de tas d’autres superbes fonctionnalités, c’est personnalisable, server-first, intégration des Islands. Bref, vous retrouverez plus d’informations sur la documentation que mon simple paragraphe. 😆

Et du coup, Starlight dans tout ça ?
Oui oui, on y vient ! Moi, je le vois tout simplement comme un membre qu’on greffe à Astro. Dans le bon terme, c’est bien un module ! Un module qui ajoute d’autres fonctionnalités spécialement pour faire une documentation, tout simplement ! Il est simple à configurer, prêt à l’emploi dès qu’on créer un nouveau projet, bref, c’est tout ce qu’on veut quand on doit avoir une documentation publié dans les temps. Je ne compte pas le fait que le site généré est responsive, ça devrait être la base. Le thème est personnalisable, et on peut bien évidemment modifier le CSS à notre guise. Après tout, c’est basé sur Astro !

Starlight 🌟

Créer des sites de documentation avec Astro Starlight

Initier le code

Pour créer un projet sous Starlight, rien de plus simple, il vous faut simplement Node.js version 18.14.1 ou au-dessus, et avoir accès à votre terminal. Sur votre client, vous pouvez l’initier en tapant :

yarn create astro --template starlight

Si vous le souhaitez, après l’installation, vous pouvez ajouter un framework comme React, Vue, Svelte, Tailwind et d’autres avec npx astro add. (Voir la documentation pour ajouter une intégration).

thomasbnt@thomasbnt:~/lab$ yarn create astro --template starlight
yarn create v1.22.19
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
success Installed "create-astro@4.6.0" with binaries:
      - create-astro

 astro   Launch sequence initiated.

   dir   Where should we create your new project?
         ./interstellar-inclination
      ◼  tmpl Using starlight as project template
 ██████  Template copying...

  deps   Install dependencies?
         Yes
 ██████  Installing dependencies with yarn...

    ts   Do you plan to write TypeScript?
         No
      ◼  No worries! TypeScript is supported in Astro by default,
         but you are free to continue writing JavaScript instead.

   git   Initialize a new git repository?
         No
      ◼  Sounds good! You can always run git init manually.

  next   Liftoff confirmed. Explore your project!

         Enter your project directory using cd ./interstellar-inclination
         Run yarn dev to start the dev server. CTRL+C to stop.
         Add frameworks like react or tailwind using astro add.

         Stuck? Join us at https://astro.build/chat

╭──❄️─╮  Houston:
│ ◠ ◡ ◠  Good luck out there, astronaut! 🚀
╰─────╯
Done in 52.80s.

Le process est si simple, au fil des années on se simplifie certaines tâches, et celle-là, le fait de ne pas devoir à chercher un package telle version et pas l’autre, je trouve ça juste top, un gain de temps. Merci Astro. 💜🚀

Cela vous donne quelque chose comme ça :

.
├── README.md
├── astro.config.mjs
├── node_modules
├── package-lock.json
├── package.json
├── public
│   └── favicon.svg
├── src
│   ├── assets
│   │   └── houston.webp
│   ├── content
│   │   ├── config.ts
│   │   └── docs
│   │       ├── guides
│   │       │   └── example.md
│   │       ├── index.mdx
│   │       └── reference
│   │           └── example.md
│   └── env.d.ts
└── tsconfig.json

Vous n’avez plus qu’à…. lancer le site web, et à aller sur http://localhost:4321/ !

yarn dev

Le contenu de votre documentation est écrit par défaut en anglais, mais tout est modifiable. Je vous rappelle que c’est du code, et que le prochain chapitre, c'est… d’éditer une page !

Modifier une page

Ouvrez votre bel IDE, vous pouvez remarquer qu’un fichier README est là pour vous guider. N’hésitez pas à le lire et à comprendre un peu comment ça marche, ainsi que d’avoir la documentation toujours à votre portée.

Nous allons directement modifier cette page que vous avez vu juste au-dessus, c’est l’index. Celle que nous verrons en arrivant sur la documentation, celle qui devrait faire la première impression et qui nous guide avec quelques informations complémentaires comme les réseaux sociaux.

Pour ce faire, nous allons dans src/content/docs/index.mdx :

Nous retrouvons le frontmatter, c’est la partie tout en haut entre les tirets ---, elle déclare le titre de la page, la description, le template utilisé et d’autres fonctionnalités que nous pouvons lui ajouter. Dans cet exemple, nous allons rester simple, car pour rappel, je ne suis pas un expert dans le domaine, et vous guider dans un endroit que même moi, je ne connais pas plus que ça, c’est comme marcher sur des orties, ça fait mal. 😆

Mais vous allez voir comment ajouter des petites choses bien sympathiques comme des badges qui font office de statut, ou encore la possibilité de mettre en avant ou pas la page.

Bref, modifions par exemple le titre, et retirons l’image Houston qui se trouve à droite (désolé).

Comme vous avez pu le voir tout juste en dessous, il y a des components,

import { Card, CardGrid } from '@astrojs/starlight/components';

## Next steps

<CardGrid stagger>
    <Card title="Update content" icon="pencil">
        Edit `src/content/docs/index.mdx` to see this page change.
    </Card>
    <Card title="Add new content" icon="add-document">
        Add Markdown or MDX files to `src/content/docs` to create new pages.
    </Card>
    <Card title="Configure your site" icon="setting">
        Edit your `sidebar` and other config in `astro.config.mjs`.
    </Card>
    <Card title="Read the docs" icon="open-book">
        Learn more in [the Starlight Docs](https://starlight.astro.build/).
    </Card>
</CardGrid>

Par défaut Starlight en intègre, mais vous pouvez en ajouter. Voir la documentation sur les Components

Passons à une page de la documentation (cliquez sur le bouton bleu si vous n’avez pas édité le code). On y voit du simple texte, c’est ici où vous pouvez documenter ce que vous souhaitez, un projet, une sorte de wiki… ce que vous souhaitez ✨

Tous les fichiers se trouvent dans /src/content/docs , et donc chaque dossier que vous faites, vous permettent de les trier. Par exemple ici dans ce cas, deux dossiers se présentent, guides/ et reference/ . Ce qui donne pour cette page /src/content/docs/guides/example.md ! D’ailleurs le fichier est en .md mais vous pouvez le modifier en .mdx . Je pense que vous aurez moins d’erreurs avec votre IDE.

Hop, on modifie tout ça pour faire quelque chose de plus complet !

astro.config.mjs

Ce fichier est important, c’est lui qui crée le menu à gauche (sidebar), les liens des réseaux sociaux en haut à droite, le titre que vous aurez en haut à gauche de la documentation, et pleines d’autres options.

Ici, je vais modifier la partie sidebar afin de référer les pages que j’ai modifiés/ajoutés pour cet exemple.

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

// https://astro.build/config
export default defineConfig({
    integrations: [
        starlight({
            title: 'Mr. Robot',
            sidebar: [
                {
                    label: 'Introduction',
                    link: '/introduction/',
                },
                {
                    label: 'Characters',
                    autogenerate: { directory: 'characters' },
                },
            ],
        }),
    ],
});

La page Introduction est seule, du coup, j'ai supprimé les items, et directement attribué un lien. Quand aux personnages, au lieu d’ajouter page par page, j’ai simplement utilisé autogenerate . Elle vous permet de… générer… automatiquement depuis votre dossier ciblé (ici characters ). Voici donc ce que ça donne :

Et voici comment est organisé mon dossier :

.
├── characters
│   ├── angelamoss.mdx
│   ├── elliotalderson.mdx
│   └── mrrobot.mdx
├── index.mdx
└── introduction.mdx

autogenerate

Par défaut avec autogenerate, les fichiers sont affichés par ordre alphabétique, mais je lui indique que la page “Mr. Robot” doit être tout au-dessus, avec l’attribue order directement dans le frontmatter. Faites très attention à la tabulation de votre frontmatter, j’ai eu pas mal d’erreurs.

---
title: "Mr. Robot"
sidebar:
  order: 1
---

Les badges

Je vous en ai parlé un peu au-dessus, et vous le voyez sur le screenshot, un badge coloré est apparu juste à droite d’un texte, et ça donne ça en code (toujours dans le frontmatter) :

sidebar:  
   order: 1  
   badge:    
      text: 'New'    
      variant: tip

Vous voyez, votre documentation prend forme très rapidement ! On a droite les étapes/titres dans la page, et à gauche votre menu qui englobe le tout. 🚀

Maintenant, nous allons voir une partie bonus de Starlight. Celle que j’aime particulièrement, celle qui rassemble les gens, l’internationalisation !

L’internationalisation (i18n)

Une documentation remplie, c’est top.
Un code source éditable par n’importe qui, c’est génial.
Partager cette documentation à l’autre bout du monde, c’est super coo…. Non du coup… et si la personne ne comprend pas ce qu'il est écrit ?

Et c’est là que l’internationalisation arrive ! 🦸‍♀️🦸‍♂️

Dans Astro Starlight, nous pouvons en quelques lignes, ajouter la possibilité de mettre la documentation en plusieurs langues. Rien n’est magique, tout est fantastique ! Non plus sérieusement, vous allez comprendre comment c’est géré avec ces bouts de codes :

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

// https://astro.build/config
export default defineConfig({
    integrations: [
        starlight({
            title: 'Mr. Robot',
            sidebar: [
                {
                    label: 'Introduction',
                    link: '/introduction/',
                },
                {
                    label: 'Characters',
                    autogenerate: { directory: 'characters' },
                    translations: {
                        fr: 'Personnages',
                    },
                },
            ],
            defaultLocale: 'root',
            locales: {
                root: {
                    label: 'English',
                    lang: 'en',
                },
                fr: {
                    label: 'Français',
                    lang: 'fr',
                },
            },
        }),
    ],
});

Ici, on défini la langue par défaut, donc en pour English. Et on a ajouté la langue fr soit Française comme un autre choix. Nous pouvons donc choisir notre langue sur le site web en haut à droite :

La liste déroulante des différentes langues disponibles pour la documentation. Ici, on a l’anglais et le français. Ce qui donne à votre dossier /src/content/docs :

.
├── characters
│   ├── angelamoss.mdx
│   ├── elliotalderson.mdx
│   └── mrrobot.mdx
├── fr
│   └── characters
│       └── elliotalderson.mdx
├── index.mdx
└── introduction.mdx

Chaque langue a son propre dossier, et dans chaque dossier le nom des dossiers doivent correspondre à celui de la langue root.

Exemple : introduction.mdx (EN) → /fr/introduction.mdx (FR)

Vous avez le guide officiel de comment bien intégrer l’i18n à votre projet.

Merci à toi d’avoir lu jusqu'au bout, n’hésite pas à partager votre documentation dans le monde entier et même ici, ça pourrait être une petite mine d’or pour certains, et une découverte pour d’autres ! Voici un exemple parfait de documentation, c’est celle de Mr. Robøt, listant les commandes et les fonctionnalités du robot Discord.