Configuration initiale du thème

1. Pour commencer, installez d’abord tous les paquets nécessaires avec npm install ou pnpm install, puis lancez une première compilation avec npm run build ou pnpm build afin de vérifier que l’installation fonctionne.
2. Copiez la compilation Pagefind (pour la recherche sur le site) afin qu’elle soit disponible dans l’environnement de développement. La procédure varie selon votre système d’exploitation. J’ai créé quelques commandes pour vous aider.
   • Sous Windows, exécutez npm run winsearch
   • Sous OSX ou Linux, exécutez npm run osxsearch
3. Ensuite, vous allez configurer l’i18n de votre site (une seule langue ou plusieurs). Exécutez simplement la commande npm run docs:config-i18n et suivez les instructions du script pour terminer la configuration !
4. Vous pouvez maintenant personnaliser le site à votre convenance !

Présentations du code

J’ai créé quelques visites guidées du code pour vous présenter la base de code. Vous aurez besoin de l’extension Code Tour pour les consulter dans VSCode ou un autre IDE.

Structure du code

Le code est organisé avec la plupart des éléments sous le répertoire src/docs. Il est ainsi facile de déposer ce dossier entier dans un projet existant et d’ajouter les fonctionnalités de documentation en quelques minutes.

Options de configuration

La configuration générale du site se fait dans le dossier src/docs/config/. La plupart des paramètres se trouvent dans des dossiers de langue distincts, ce qui facilite la gestion des traductions.

Paramètres du site

Le fichier src/docs/config/siteSettings.json.ts sert à configurer les paramètres du site. Ceux-ci comprennent notamment l’activation des transitions de vue, l’activation des animations et l’affichage des boutons de copie de lien pour les titres de la documentation.

Données du site

Le fichier src/docs/config/[language]/siteData.json.ts sert à configurer les données du site. Cela comprend notamment le titre du site, sa description, les liens vers les réseaux sociaux et l’image par défaut.

Données de navigation

Configurez les données de navigation de la barre supérieure dans le fichier src/docs/config/[language]/navData.json.ts.

Mise en page de la barre latérale

Configurez l’ordre des sections de votre documentation dans le fichier src/docs/config/[language]/sidebarNavData.json.ts.

Robots

Pour que les robots comme celui de Google voient le bon sitemap, modifiez le fichier public/robots.txt afin d’utiliser le domaine de votre site.

Ressources supplémentaires

Informations générales sur Astro

Astro recherche les fichiers .astro ou .md dans le répertoire src/pages/. Chaque page est exposée comme une route basée sur son nom de fichier.

Le dossier src/components/ n’a rien de particulier, mais c’est là que nous aimons placer les composants Astro/React/Vue/Svelte/Preact.

Les ressources statiques, comme les images, peuvent être placées dans le répertoire public/. J’utilise aussi fréquemment src/assets pour les images lorsque je fais appel aux assets d’Astro pour l’optimisation des images.

Commandes

Toutes les commandes s’exécutent depuis la racine du projet, dans un terminal :

| Commande | Action | | :------------------------ | :----------------------------------------------- | | npm install | Installe les dépendances | | npm run dev | Démarre le serveur local sur localhost:4321 | | npm run build | Compile votre site de production dans ./dist/ | | npm run preview | Prévisualise votre compilation avant déploiement | | npm run astro ... | Exécute des commandes CLI comme astro add, astro check | | npm run astro -- --help | Obtient de l’aide sur la CLI Astro |

Envie d’en savoir plus ?

N’hésitez pas à consulter la documentation ou à rejoindre le serveur Discord.