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.

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;
}
```

Ajoutez le chemin vers votre fichier CSS au tableau customCss de Starlight dans votre configuration 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 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 la couche starlight :

@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

La prise en charge de Tailwind CSS v4 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 create astro@latest -- --template starlight/tailwind

pnpm create astro --template starlight/tailwind

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.

Initialisez Tailwind dans votre projet en exécutant la commande suivante et en suivant les instructions dans votre terminal :
- npm
- pnpm
- Yarn
Fenêtre de terminal
npx astro add tailwind
Fenêtre de terminal
pnpm astro add tailwind
Fenêtre de terminal
yarn astro add tailwind
Installez le paquet de compatibilité Tailwind de Starlight :
- npm
- pnpm
- Yarn
Fenêtre de terminal
npm install @astrojs/starlight-tailwind
Fenêtre de terminal
pnpm add @astrojs/starlight-tailwind
Fenêtre de terminal
yarn add @astrojs/starlight-tailwind
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);
```
Cette configuration de thème Tailwind définit l’ordre des couches de cascade de Starlight, importe le CSS complémentaire de Starlight pour Tailwind et importe les styles des thèmes et utilitaires de Tailwind. Si votre projet nécessite une configuration Tailwind supplémentaire, consultez la section « Utiliser plusieurs configurations Tailwind ».

Mettez à jour la configuration de Starlight pour ajouter le fichier CSS Tailwind en tant que premier élément du tableau customCss :

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

Lors de la création d’un nouveau projet Starlight avec Tailwind, ou lors de l’ajout de Tailwind à un projet Starlight existant, Starlight utilisera les valeurs de votre configuration de thème Tailwind située dans le fichier src/styles/global.css pour mettre en forme 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ée pour les liens et la mise en évidence de l’élément courant
--color-gray-* — utilisée pour les couleurs d’arrière-plan et les bordures
--font-sans — utilisée pour le texte de l’interface utilisateur et du contenu
--font-mono — utilisée pour les exemples de code

@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);
}

Utiliser plusieurs configurations Tailwind

Plusieurs configurations Tailwind peuvent être utilisées pour appliquer différents styles à différentes parties de votre site, par exemple lorsque vous utilisez Starlight dans un sous-chemin ou lorsque vous ajoutez des pages personnalisées à votre site. Par exemple, vous souhaiterez peut-être utiliser les styles de réinitialisation Preflight de Tailwind dans vos pages personnalisées, tout en appliquant la couche de compatibilité de Starlight aux pages Starlight.

La configuration Tailwind CSS suivante configure Tailwind sans aucun module d’extension ni configuration supplémentaire et peut être utilisée comme point de départ pour les pages non gérées par Starlight :

/* Charge Tailwind sans aucun CSS complémentaire provenant de Starlight. */
@import 'tailwindcss';

Pour les pages Starlight, appliquez votre configuration Tailwind CSS préférée en suivant « Ajouter Tailwind à un projet existant ».
Pour les autres pages, appliquez votre configuration Tailwind CSS préférée en l’important dans ces pages. Cette opération est souvent effectuée dans un composant de mise en page afin que les styles de Tailwind puissent être utilisés sur toutes les pages partageant cette mise en page.
src/layouts/CustomPageLayout.astro
```
---
import '../styles/custom-pages-tailwind.css';
---
```

Pour en savoir plus sur les configurations de thème Tailwind, consultez la documentation de Tailwind CSS.

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

Niveau de contraste

AA AAA

Accentuation

Teinte 269

Chroma 0.27

Gris

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.

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

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