Zum Inhalt springen
Starlight

CSS & Styling

Du kannst deine Starlight-Website mit benutzerdefinierten CSS-Dateien gestalten oder das Starlight Tailwind-Plugin verwenden.

Eine schnelle Möglichkeit, das Standardtheme deiner Website zu ändern, findest du unter Cummunity-Themes.

Benutzerdefinierte CSS-Styles (Stile)

Abschnitt betitelt „Benutzerdefinierte CSS-Styles (Stile)“

Passe die Styles deiner Starlight-Website an, indem du zusätzliche CSS-Dateien bereitstellst, um die Standard-Styles von Starlight zu verändern oder zu erweitern.

  1. Füge eine CSS-Datei zu deinem src/-Verzeichnis hinzu. Du kannst zum Beispiel eine größere Standard-Spaltenbreite und eine größere Textgröße für den Seitentitel festlegen:

    src/styles/custom.css
    :root {
      --sl-content-width: 50rem;
      --sl-text-5xl: 3.5rem;
    }

  2. Füge den Pfad zu deiner CSS-Datei in Starlights customCss- Array in astro.config.mjs ein:

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

    export default defineConfig({
      integrations: [
        starlight({
          title: 'Dokumentation mit benutzerdefiniertem CSS',
          customCss: [
            // Relativer Pfad zu deiner benutzerdefinierten CSS-Datei
            './src/styles/custom.css',
          ],
        }),
      ],
    });

Du kannst dir alle CSS-Eigenschaften, die von Starlight verwendet werden und die du einstellen kannst, um deine Website anzupassen, in der Datei props.css auf GitHub ansehen.

Kaskadenschichten

Abschnitt betitelt „Kaskadenschichten“

Starlight verwendet intern Kaskadenschichten, um die Reihenfolge der Stile zu verwalten. Dies gewährleistet eine vorhersehbare CSS-Reihenfolge und ermöglicht einfachere Überschreibungen. Jedes benutzerdefinierte CSS ohne Schichten überschreibt die Standardstile der Schicht starlight.

Wenn du Kaskadenschichten verwendest, kannst du @layer in deinem benutzerdefinierten CSS verwenden, um die Rangfolge der verschiedenen Schichten in Bezug auf die Stile von Starlight festzulegen:

src/styles/custom.css
@layer my-reset, starlight, my-overrides;

Das obige Beispiel definiert eine benutzerdefinierte Schicht namens my-reset, die vor allen Starlight-Schichten angewendet wird, und eine weitere Schicht namens my-overrides, die nach allen Starlight-Schichten angewendet wird. Alle Stile in der Schicht my-overrides haben Vorrang vor den Stilen von Starlight, aber Starlight kann immer noch Stile ändern, die in der Schicht my-reset festgelegt wurden.

Tailwind CSS

Abschnitt betitelt „Tailwind CSS“

Tailwind CSS-Unterstützung in Astro-Projekten wird durch die Tailwind Vite-Plugin bereitgestellt. Starlight bietet komplementäres CSS, um Tailwind für die Kompatibilität mit den Styles von Starlight zu konfigurieren.

Das Starlight Tailwind CSS wendet die folgende Konfiguration an:

  • Konfiguriert Tailwinds dark:-Varianten so, dass sie mit Starlights Dark Mode funktionieren.
  • Verwendet Tailwind Themenfarben und Schriftarten in Starlights UI.
  • Stellt wesentliche Teile der Preflight-Reset-Stile von Tailwind wieder her.

Erstelle ein neues Projekt mit Tailwind

Abschnitt betitelt „Erstelle ein neues Projekt mit Tailwind“

Starte ein neues Starlight-Projekt mit Tailwind CSS vorkonfiguriert, indem du create astro verwendest:

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

Tailwind zu einem bestehenden Projekt hinzufügen

Abschnitt betitelt „Tailwind zu einem bestehenden Projekt hinzufügen“

Wenn du bereits eine Starlight-Website hast und Tailwind CSS hinzufügen möchtest, folge dieser Anleitung.

  1. Richte Tailwind in deinem Projekt ein, indem du den folgenden Befehl ausführst und den Anweisungen in deinem Terminal folgst:

    Terminal-Fenster
    npx astro add tailwind

  2. Installiere das Tailwind-Kompatibilitätspaket von Starlight:

    Terminal-Fenster
    npm install @astrojs/starlight-tailwind

  3. Ersetze den Inhalt der Datei src/styles/global.css, die von Astro für die Kompatibilität mit Starlight gerüstet wurde:

    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. Aktualisiere die Starlight-Konfiguration, um die Tailwind-CSS-Datei zu verwenden:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    import tailwindcss from '@tailwindcss/vite';
    

    export default defineConfig({
      integrations: [
        starlight({
          title: 'Dokumentation mit Tailwind',
          customCss: [
            // Pfad zu deinen grundlegenden Tailwind-Styles
            './src/styles/global.css',
          ],
        }),
      ],
      vite: { plugins: [tailwindcss()] },
    });

Starlight mit Tailwind designen

Abschnitt betitelt „Starlight mit Tailwind designen“

Starlight verwendet Werte aus deiner Tailwind-Theme-Konfiguration in der Benutzeroberfläche.

Wenn diese Option aktiviert ist, überschreiben die folgenden benutzerdefinierten CSS-Eigenschaften die Standardstile von Starlight:

  • --color-accent-* - wird für Links und die Hervorhebung des aktuellen Elements verwendet
  • --color-gray-* - wird für Hintergrundfarben und Rahmen verwendet
  • --font-sans - wird für UI und Inhaltstext verwendet
  • --font-mono - wird für Code-Beispiele verwendet
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 {
  /*
  Deine bevorzugte Schriftart.
  Starlight verwendet standardmäßig eine Systemschriftart.
  */
  --font-sans: 'Atkinson Hyperlegible';
  /*
  Deine bevorzugte Code-Schriftart.
  Starlight verwendet standardmäßig die Systemschriftart Monospace.
  */
  --font-mono: 'IBM Plex Mono';
  /*
  Deine bevorzugte Akzentfarbe.
  Indigo entspricht am ehesten den Standardeinstellungen von 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);
  /*
  Deine bevorzugte Grauskala.
  Zink kommt den Standardeinstellungen von Starlight am nächsten.
  */
  --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);
}

Themes

Abschnitt betitelt „Themes“

Das Farbtheme von Starlight kann gesteuert werden, indem die Standard­einstellungen überschrieben werden. Diese Variablen werden in der gesamten Benutzeroberfläche verwendet, wobei eine Reihe von Grautönen für Text- und Hintergrundfarben sowie eine Akzentfarbe für Links und zur Hervorhebung aktueller Elemente in der Navigation verwendet werden.

Farbdesign-Editor

Abschnitt betitelt „Farbdesign-Editor“

Verwende die Schieberegler unten, um die Akzent- und Graufarbpalette von Starlight zu ändern. Die dunklen und hellen Vorschaubereiche zeigen die resultierenden Farben, und die gesamte Seite wird ebenfalls aktualisiert, um deine Änderungen anzuzeigen.

Verwende die Option Kontraststufe, um festzulegen, welche der Richtlinie für die Zugänglichkeit von Webinhalten Farbkontrast­standards erfüllt werden soll.

Wenn du mit deinen Änderungen zufrieden bist, kopiere den CSS- oder Tailwind-Code unten und verwende ihn in deinem Projekt.

Voreinstellungen
Kontraststufe
Akzent
Grau

Dark mode

Der Fließtext wird in einem Grauton mit hohem Kontrast zum Hintergrund dargestellt. Links sind farbig. Einige Texte, wie z. B. das Inhaltsverzeichnis, haben einen geringeren Kontrast. Inline-Code hat einen eindeutigen Hintergrund.

Light mode

Der Fließtext wird in einem Grauton mit hohem Kontrast zum Hintergrund dargestellt. Links sind farbig. Einige Texte, wie z. B. das Inhaltsverzeichnis, haben einen geringeren Kontrast. Inline-Code hat einen eindeutigen Hintergrund.

Füge das folgende CSS in deinem Projekt in eine benutzerdefinierte CSS-Datei ein, um dieses Theme auf deiner Website anzuwenden.