Personnaliser Starlight

Starlight propose par défaut un style et des fonctionnalités pragmatiques, vous pouvez donc démarrer rapidement sans configuration nécessaire. Lorsque vous souhaitez commencer à personnaliser l’apparence de votre site Starlight, ce guide vous accompagne.

Ajouter votre logo

L’ajout d’un logo personnalisé à l’en-tête du site est un moyen rapide d’ajouter votre image de marque personnelle à un site Starlight.

Ajoutez votre fichier logo au répertoire src/assets/ :
- Directorysrc/
  - Directoryassets/
    mon-logo.svg
  - Directorycontent/
    …
- astro.config.mjs

Ajoutez le chemin vers votre logo à votre option de configuration Starlight logo.src dans astro.config.mjs:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs Avec Mon Logo',
      logo: {
        src: './src/assets/mon-logo.svg',
      },
    }),
  ],
});

Par défaut, le logo sera affiché à côté du nom de votre site (option title dans la configuration). Si l’image de votre logo inclut déjà le titre du site, vous pouvez masquer visuellement le texte du titre en définissant l’option replacesTitle à true. Le texte du titre (title) le texte sera toujours inclus pour les lecteurs d’écran afin que l’en-tête reste accessible.

starlight({
  title: 'Docs Avec Mon Logo',
  logo: {
    src: './src/assets/mon-logo.svg',
    replacesTitle: true,
  },
}),

Variantes claires et sombres de votre logo

Vous pouvez afficher différentes versions de votre logo en modes clair et sombre.

Ajouter un fichier image pour chaque variante dans src/assets/:
- Directorysrc/
  - Directoryassets/
    logo-clair.svg
    logo-sombre.svg
  - Directorycontent/
    …
- astro.config.mjs

Ajouter les chemins vers vos variantes de logo dans les options light (clair) et dark (sombre) en remplacement de l’option src dans astro.config.mjs:

starlight({
  title: 'Docs Avec Mon Logo',
  logo: {
    light: './src/assets/logo-clair.svg',
    dark: './src/assets/logo-sombre.svg',
  },
}),

Activer un plan de site

Starlight possède une prise en charge intégrée pour la génération d’un plan de site. Activez la génération du plan de site en définissant votre URL comme site dans astro.config.mjs:

export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [starlight({ title: 'Site avec un plan de site' })],
});

Mise en Page

Par défaut, les pages Starlight utilisent une mise en page avec une barre latérale de navigation globale et une table des matières qui affiche les titres de la page courante.

Vous pouvez appliquer une mise en page plus large sans barres latérales en définissant template: splash dans le frontmatter de votre page. Cela fonctionne particulièrement bien pour les pages d’atterissage et vous pouvez le voir en action sur la page d’accueil de ce site.

---
title: Ma page d’atterissage
template: splash
---

Table des matières

Starlight affiche une table des matières sur chaque page pour permettre aux lecteurs d’accéder plus facilement à la section qu’ils recherchent. Vous pouvez personnaliser - ou même désactiver - la table des matières globalement dans l’intégration Starlight ou page par page dans votre frontmatter.

Par défaut, les titres <h2> et <h3> sont inclus dans la table des matières. Modifiez les niveaux de titres à inclure à l’échelle du site à l’aide des options minHeadingLevel et maxHeadingLevel dans votre option de configuration globale tableOfContents. Remplacez ces valeurs par défaut sur une page individuelle en ajoutant les propriétés frontmatter tableOfContents correspondantes :

Frontmatter
Configuration globale

---
title: Page avec seulement les H2s dans la table des matières
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---

defineConfig({
  integrations: [
    starlight({
      title: 'Site avec une configuration de table des matières personnalisée',
      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
    }),
  ],
});

Désactivez la table des matières complètement en définissant l’option tableOfContents à false:

Frontmatter
Configuration globale

---
title: Page sans table des matières
tableOfContents: false
---

defineConfig({
  integrations: [
    starlight({
      title: 'Site avec la table des matières désactivée globalement',
      tableOfContents: false,
    }),
  ],
});

Liens sociaux

Starlight supporte par défaut l’ajout de liens vers vos comptes de médias sociaux dans l’en-tête du site via l’option social dans l’intégration Starlight.

Vous pouvez retrouver une liste complète des icônes de liens prises en charge dans la référence de configuration. Faites-nous savoir sur GitHub ou Discord si vous avez besoin de la prise en charge d’un autre service !

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Site avec des liens sociaux',
      social: {
        discord: 'https://astro.build/chat',
        github: 'https://github.com/withastro/starlight',
      },
    }),
  ],
});

Liens d’édition de page

Starlight peut afficher un lien “Modifier cette page” dans le pied de page de chaque page. Cela permet au lecteur de trouver facilement le fichier à modifier pour améliorer vos documents. Pour les projets open source en particulier, cela peut aider à encourager les contributions de votre communauté.

Pour activer les liens de modification, définissez l’option de configuration editLink.baseUrl en lui assignant l’URL utilisée pour modifier votre référentiel dans la configuration de l’intégration Starlight. La valeur de editLink.baseUrl sera automatiquement ajoutée au chemin d’accès vers la page actuelle pour former le lien d’édition complet.

Les formes d’URL les plus courantes incluent :

GitHub: https://github.com/NOM_UTILISATEUR/NOM_DU_DEPOT/edit/NOM_DE_LA_BRANCHE/
GitLab: https://gitlab.com/NOM_UTILISATEUR/NOM_DU_DEPOT/-/edit/NOM_DE_LA_BRANCHE/

Si votre projet Starlight ne se trouve pas à la racine de votre dépôt, incluez le chemin d’accès au projet à la fin de l’URL de base.

Cet exemple montre le lien d’édition configuré pour les documents Starlight, qui se trouvent dans le sous-répertoire docs/ sur la branche main du dépôt withastro/starlight sur GitHub :

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Sites avec liens d’édition de page',
      editLink: {
        baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
      },
    }),
  ],
});

Page 404 personnalisée

Les sites Starlight affichent par défaut une simple page 404. Vous pouvez personnaliser cela en ajoutant un fichier 404.md (ou 404.mdx) à votre répertoire src/content/docs/ :

Directorysrc/
- Directorycontent/
  - Directorydocs/
    404.md
    index.md
astro.config.mjs

Vous pouvez utiliser toutes les techniques de mise en page et de personnalisation de Starlight dans votre page 404. Par exemple, la page 404 par défaut utilise la mise en page splash et le composant hero dans son frontmatter :

---
title: '404'
template: splash
editUrl: false
hero:
  title: '404'
  tagline: Page introuvable. Vérifiez l’URL ou essayez la barre de recherche.
---

Polices personnalisées

Par défaut, Starlight utilise des polices sans empattement disponibles en local sur la machine du visiteur pour tout les textes. Cela garantit que la documentation se charge rapidement dans une police familière à chaque utilisateur, sans nécessiter de bande passante supplémentaire pour télécharger des fichiers de police volumineux.

Si vous souhaitez ajouter une police personnalisée à votre site Starlight, vous pouvez configurer les polices à utiliser dans des fichiers CSS personnalisés ou avec toute autre technique de style Astro.

Configurer les polices

Si vous avez déjà des fichiers de polices, suivez le guide de configuration local. Pour utiliser Google Fonts, suivez le Guide de configuration de Fontsource.

Configurer les polices localement

Ajoutez vos fichiers de polices dans un répertoire src/fonts/ et créez un fichier font-face.css vide :
- Directorysrc/
  - Directorycontent/
    …
  - Directoryfonts/
    PolicePersonnalisee.woff2
    font-face.css
- astro.config.mjs

Ajoutez une déclaration @font-face pour chacune de vos polices dans src/fonts/font-face.css. Utilisez le chemin relatif vers le fichier de police dans la fonction url().

@font-face {
  font-family: 'Police Personnalisee';
  /* Utilisez le chemin relatif vers le fichier de police dans la fonction `url()`. */
  src: url('./PolicePersonnalisee.woff2') format('woff2');
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

Ajoutez le chemin de votre fichier font-face.css au tableau customCss de Starlight dans astro.config.mjs :

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Site avec polices personnalisées',
      customCss: [
        // Chemin relatif vers votre fichier CSS @font-face.
        '/src/fonts/font-face.css',
      ],
    }),
  ],
});

Configurer les polices avec Fontsource

Le projet Fontsource simplifie l’utilisation des polices Google et d’autres polices open source. Il fournit des modules npm que vous pouvez installer pour les polices que vous souhaitez utiliser et inclut des fichiers CSS prêts à l’emploi à ajouter à votre projet.

Trouvez la police que vous souhaitez utiliser dans le catalogue de Fontsource. Cet exemple utilisera IBM Plex Serif.
Installez le package pour la police choisie. Vous pouvez trouver le nom du package en cliquant sur “Installer” sur la page de police Fontsource.
- npm
- pnpm
- Yarn
Terminal window
npm install @fontsource/ibm-plex-serif
Terminal window
pnpm install @fontsource/ibm-plex-serif
Terminal window
yarn add @fontsource/ibm-plex-serif

Ajoutez les fichiers CSS Fontsource au tableau customCss de Starlight dans astro.config.mjs :

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

export default defineConfig({
  integrations: [
    starlight({
      title: "Site avec polices personnalisées Fontsource",
      customCss: [
        // Fichiers Fontsource pour les graisses regular et semi-bold.
        "@fontsource/ibm-plex-serif/400.css",
        "@fontsource/ibm-plex-serif/600.css",
      ],
    }),
  ],
});

Fontsource fournit plusieurs fichiers CSS pour chaque police. Consultez la documentation Fontsource sur l’inclusion de différentes graisses et styles pour comprendre lesquels utiliser.

Utiliser vos polices personnalisées

Une fois configurée, pour appliquer votre police personnalisée à votre site, utilisez le nom de la police que vous avez choisie dans un fichier CSS personnalisé. Par exemple, pour remplacer la police par défaut de Starlight partout, définissez la propriété personnalisée --sl-font :

:root {
  --sl-font: 'IBM Plex Serif', serif;
}

Vous pouvez également écrire du CSS plus ciblé si vous souhaitez appliquer votre police de manière plus sélective. Par exemple, pour définir uniquement une police sur le contenu principal, mais pas sur les barres latérales :

main {
  font-family: 'IBM Plex Serif', serif;
}

Suivez les instructions de CSS personnalisé pour ajouter vos styles à votre site.