CSS et mise en forme

Vous pouvez mettre en forme votre site Starlight avec du CSS personnalisé ou utiliser le module d’extension Tailwind de Starlight.

Pour changer rapidement l’apparence par défaut de votre site, consultez les thèmes communautaires.

Styles CSS personnalisés

Personnalisez les styles appliqués à votre site Starlight en fournissant des fichiers CSS supplémentaires pour modifier ou étendre les styles par défaut de Starlight.

1. Ajoutez un fichier CSS à votre répertoire src/. Par exemple, vous pouvez définir une largeur de colonne par défaut plus large et une taille de texte plus grande pour les titres de page :

   src/styles/custom.css

   :root {
     --sl-content-width: 50rem;
     --sl-text-5xl: 3.5rem;
   }

2. Ajoutez le chemin vers votre fichier CSS au tableau customCss de Starlight dans votre configuration astro.config.mjs :

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'Documentation avec CSS personnalisé',
         customCss: [
           // Chemin relatif vers votre fichier CSS personnalisé
           './src/styles/custom.css',
         ],
       }),
     ],
   });

Vous pouvez retrouver toutes les propriétés CSS personnalisées utilisées par Starlight que vous pouvez définir pour personnaliser votre site dans le fichier props.css sur GitHub.

Couche de cascade

Starlight utilise les couches de cascade en interne pour gérer l’ordre de ses styles. Cela garantit un ordre CSS prévisible et permet des redéfinitions plus simples. N’importe quel CSS personnalisé ne faisant pas partie d’une couche de cascade redéfinira les styles par défaut de la couche starlight.

Si vous utilisez des couches de cascade, vous pouvez utiliser @layer dans votre CSS personnalisé pour définir l’ordre de priorité pour différentes couches par rapport aux styles de Starlight :

src/styles/custom.css

@layer ma-reinitialisation, starlight, mes-redefinitions;

L’exemple ci-dessus définit une couche personnalisée nommée ma-reinitialisation, appliquée avant toutes les couches de Starlight, et une autre nommée mes-redefinitions, appliquée après toutes les couches de Starlight. N’importe quel style dans la couche mes-redefinitions aurait priorité sur les styles de Starlight, mais Starlight pourrait toujours changer les styles définis dans la couche ma-reinitialisation.

Tailwind CSS

Le support de Tailwind CSS dans les projets Astro est fourni par le module d’extension Vite pour Tailwind. Starlight fournit du CSS additionnel pour aider à configurer Tailwind pour une compatibilité avec les styles de Starlight.

Le CSS Tailwind de Starlight applique la configuration suivante :

• Configure les variantes dark: de Tailwind pour fonctionner avec le mode sombre de Starlight.
• Utilise les couleurs et polices de thème de Tailwind dans l’interface utilisateur de Starlight.
• Restaure des parties essentielles des styles de réinitialisation Preflight de Tailwind.

Créer un nouveau projet avec Tailwind

Démarrez un nouveau projet Starlight avec Tailwind CSS préconfiguré en utilisant create astro :

npm

npm create astro@latest -- --template starlight/tailwind

pnpm

pnpm create astro --template starlight/tailwind

Yarn

yarn create astro --template starlight/tailwind

Ajouter Tailwind à un projet existant

Si vous avez déjà un site Starlight et que vous souhaitez ajouter Tailwind CSS, suivez ces étapes.

1. Initialisez Tailwind dans votre projet en exécutant la commande suivante et en suivant les instructions dans votre terminal :

   npm

   npx astro add tailwind

   pnpm

   pnpm astro add tailwind

   Yarn

   yarn astro add tailwind

2. Installez le paquet de compatibilité Tailwind de Starlight :

   npm

   npm install @astrojs/starlight-tailwind

   pnpm

   pnpm add @astrojs/starlight-tailwind

   Yarn

   yarn add @astrojs/starlight-tailwind

3. Remplacez le contenu du fichier src/styles/global.css créé par Astro pour une compatibilité avec Starlight :

   src/styles/global.css

   @layer base, starlight, theme, components, utilities;
   
   @import '@astrojs/starlight-tailwind';
   @import 'tailwindcss/theme.css' layer(theme);
   @import 'tailwindcss/utilities.css' layer(utilities);

4. Mettez à jour la configuration de Starlight pour utiliser le fichier CSS Tailwind :

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   import tailwindcss from '@tailwindcss/vite';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'Documentation avec Tailwind',
         customCss: [
           // Chemin vers vos style de base de Tailwind:
           './src/styles/global.css',
         ],
       }),
     ],
     vite: { plugins: [tailwindcss()] },
   });

Mettre en forme Starlight avec Tailwind

Starlight utilise les valeurs de votre configuration de thème Tailwind dans son interface utilisateur.

Si définies, les propriétés personnalisées CSS suivantes remplaceront les styles par défaut de Starlight :

• --color-accent-* — utilisé pour les liens et la mise en évidence de l’élément courant
• --color-gray-* — utilisé pour les couleurs d’arrière-plan et les bordures
• --font-sans — utilisé pour le texte de l’interface utilisateur et du contenu
• --font-mono — utilisé pour les exemples de code

src/styles/global.css

@layer base, starlight, theme, components, utilities;

@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

@theme {
  /*
  Votre police de texte préférée.
  Starlight utilise une pile de polices système par défaut.
  */
  --font-sans: 'Atkinson Hyperlegible';
  /*
  Votre police de code préférée.
  Starlight utilise des polices système à chasse fixe par défaut.
  */
  --font-mono: 'IBM Plex Mono';
  /*
  Votre couleur d'accentuation préférée.
  Indigo est la plus proche des valeurs par défaut de Starlight.
  */
  --color-accent-50: var(--color-indigo-50);
  --color-accent-100: var(--color-indigo-100);
  --color-accent-200: var(--color-indigo-200);
  --color-accent-300: var(--color-indigo-300);
  --color-accent-400: var(--color-indigo-400);
  --color-accent-500: var(--color-indigo-500);
  --color-accent-600: var(--color-indigo-600);
  --color-accent-700: var(--color-indigo-700);
  --color-accent-800: var(--color-indigo-800);
  --color-accent-900: var(--color-indigo-900);
  --color-accent-950: var(--color-indigo-950);
  /*
  Votre échelle de gris préférée.
  Zinc est la plus proche des valeurs par défaut de Starlight.
  */
  --color-gray-50: var(--color-zinc-50);
  --color-gray-100: var(--color-zinc-100);
  --color-gray-200: var(--color-zinc-200);
  --color-gray-300: var(--color-zinc-300);
  --color-gray-400: var(--color-zinc-400);
  --color-gray-500: var(--color-zinc-500);
  --color-gray-600: var(--color-zinc-600);
  --color-gray-700: var(--color-zinc-700);
  --color-gray-800: var(--color-zinc-800);
  --color-gray-900: var(--color-zinc-900);
  --color-gray-950: var(--color-zinc-950);
}

Personnalisation du thème

Le thème de couleur de Starlight peut être contrôlé en remplaçant ses propriétés personnalisées par défaut. Ces variables sont utilisées dans toute l’interface utilisateur avec une gamme de nuances de gris utilisées pour les couleurs de texte et d’arrière-plan et une couleur d’accentuation utilisée pour les liens et pour mettre en évidence les éléments courants durant la navigation.

Éditeur de thème de couleur

Utilisez les contrôles ci-dessous pour modifier les palettes de couleurs d’accentuation et de gris de Starlight. Les zones d’aperçu sombre et clair afficheront les couleurs résultantes, et la page entière sera également mise à jour pour prévisualiser vos modifications.

Utilisez l’option Niveau de contraste pour spécifier lequel des standards de contraste de couleur des règles pour l’accessibilité des contenus Web à respecter.

Quand vous êtes satisfait de vos modifications, copiez le code CSS ou Tailwind ci-dessous et utilisez-le dans votre projet.

Préréglages Océan Forêt Oxyde Nébuleuse Par défaut Aléatoire

Niveau de contraste

AA AAA

Accentuation

Choisissez une couleur

Teinte 269 Chroma 0.27

Gris

Choisissez une couleur

Teinte 270 Chroma 0.016

Mode sombre

Le corps du texte est affiché dans une teinte grise avec un contraste élevé avec l'arrière-plan. Les liens sont colorés. Certains textes, comme la table des matières, ont un contraste plus faible. Le code en ligne a un arrière-plan distinct.

Mode clair

Le corps du texte est affiché dans une teinte grise avec un contraste élevé avec l'arrière-plan. Les liens sont colorés. Certains textes, comme la table des matières, ont un contraste plus faible. Le code en ligne a un arrière-plan distinct.

CSS

Ajouter le code CSS suivant à votre projet dans un fichier CSS personnalisé pour appliquer ce thème à votre site.

Tailwind

Ajouter les propriétés personnalisées CSS suivantes au bloc @theme dans votre fichier CSS Tailwind pour appliquer ce thème à votre site.