Plugins Reference

Starlight-Plugins können die Konfiguration, Benutzeroberfläche und das Verhalten von Starlight anpassen und sind gleichzeitig einfach zu teilen und wiederzuverwenden. Diese Referenzseite dokumentiert die API, auf die Plugins Zugriff haben.

Erfahren Sie mehr über die Verwendung eines Starlight-Plugins im Configuration Reference oder besuchen Sie plugins showcase, um eine Liste der verfügbaren Plugins anzuzeigen.

Quick API Reference

Ein Starlight-Plugin hat die folgende Form. Einzelheiten zu den verschiedenen Eigenschaften und Hook-Parametern finden Sie weiter unten.

interface StarlightPlugin {
  name: string;
  hooks: {
    'i18n:setup'?: (options: {
      injectTranslations: (
        translations: Record<string, Record<string, string>>
      ) => void;
    }) => void | Promise<void>;
    'config:setup': (options: {
      config: StarlightUserConfig;
      updateConfig: (newConfig: StarlightUserConfig) => void;
      addIntegration: (integration: AstroIntegration) => void;
      addRouteMiddleware: (config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void;
      astroConfig: AstroConfig;
      command: 'dev' | 'build' | 'preview';
      isRestart: boolean;
      logger: AstroIntegrationLogger;
      useTranslations: (lang: string) => I18nT;
      absolutePathToLang: (path: string) => string;
    }) => void | Promise<void>;
  };
}

`name`

type: string

Ein Plugin muss einen eindeutigen Namen haben, der es beschreibt. Der Name wird verwendet, wenn logging messages sich auf dieses Plugin bezieht, und kann von anderen Plugins verwendet werden, um das Vorhandensein dieses Plugins zu erkennen.

`hooks`

Hooks sind Funktionen, die Starlight aufruft, um Plugin-Code zu bestimmten Zeiten auszuführen.

Um den Typ der Argumente eines Hooks abzurufen, verwenden Sie den Diensttyp HookParameters und übergeben Sie den Hook-Namen. Im folgenden Beispiel wird der Parameter options so typisiert, dass er mit den Argumenten übereinstimmt, die an den Hook config:setup übergeben werden:

import type { HookParameters } from '@astrojs/starlight/types';

function configSetup(options: HookParameters['config:setup']) {
  options.useTranslations('en');
}

`i18n:setup`

Die Setup-Funktion für die Plugin-Internationalisierung wird aufgerufen, wenn Starlight initialisiert wird. Mit dem Hook i18n:setup können Übersetzungszeichenfolgen eingefügt werden, sodass ein Plugin verschiedene Gebietsschemas unterstützen kann. Diese Übersetzungen werden über useTranslations() im config:setup-Hook und in UI-Komponenten über Astro.locals.t() verfügbar sein.

Der i18n:setup-Hook wird mit den folgenden Optionen aufgerufen:

`injectTranslations`

type: (translations: Record<string, Record<string, string>>) => void

A callback function to add or update translation strings used in Starlight’s localization APIs.

Im folgenden Beispiel fügt ein Plugin Übersetzungen für eine benutzerdefinierte UI-Zeichenfolge namens myPlugin.doThing für die Gebietsschemata en und fr ein:

export default {
  name: 'plugin-with-translations',
  hooks: {
    'i18n:setup'({ injectTranslations }) {
      injectTranslations({
        en: {
          'myPlugin.doThing': 'Do the thing',
        },
        fr: {
          'myPlugin.doThing': 'Faire le truc',
        },
      });
    },
  },
};

Um die eingefügten Übersetzungen in Ihrer Plugin-Benutzeroberfläche zu verwenden, befolgen Sie die Anweisungen “Using UI translations” guide. Wenn Sie UI-Strings im Kontext des config:setup-Hooks Ihres Plugins verwenden müssen, können Sie den useTranslations()-Callback verwenden.

Typen für die injizierten Übersetzungszeichenfolgen eines Plugins werden automatisch im Projekt eines Benutzers generiert, sind jedoch noch nicht verfügbar, wenn Sie in der Codebasis Ihres Plugins arbeiten. Um das locals.t-Objekt im Kontext Ihres Plugins einzugeben, deklarieren Sie die folgenden globalen Namespaces in einer TypeScript-Deklarationsdatei:

declare namespace App {
  type StarlightLocals = import('@astrojs/starlight').StarlightLocals;
  // Define the `locals.t` object in the context of a plugin.
  interface Locals extends StarlightLocals {}
}

declare namespace StarlightApp {
  // Define the additional plugin translations in the `I18n` interface.
  interface I18n {
    'myPlugin.doThing': string;
  }
}

Sie können die Typen für die Schnittstelle StarlightApp.I18n auch aus einer Quelldatei ableiten, wenn Sie über ein Objekt verfügen, das Ihre Übersetzungen enthält.

Nehmen wir zum Beispiel die folgende Quelldatei:

export const UIStrings = {
  en: { 'myPlugin.doThing': 'Do the thing' },
  fr: { 'myPlugin.doThing': 'Faire le truc' },
};

Die folgende Deklaration würde Typen aus den englischen Schlüsseln in der Quelldatei ableiten:

declare namespace StarlightApp {
  type UIStrings = typeof import('./ui-strings').UIStrings.en;
  interface I18n extends UIStrings {}
}

`config:setup`

Plugin-Konfigurations-Setup-Funktion, die aufgerufen wird, wenn Starlight initialisiert wird (während des astro:config:setup-Integrations-Hooks). Mit dem Hook config:setup können Sie die Starlight-Konfiguration aktualisieren oder Astro-Integrationen hinzufügen.

Dieser Hook wird mit den folgenden Optionen aufgerufen:

`config`

type: StarlightUserConfig

Eine schreibgeschützte Kopie des vom Benutzer bereitgestellten Starlight configuration. Diese Konfiguration wurde möglicherweise durch andere Plugins aktualisiert, die vor der aktuellen konfiguriert wurden.

`updateConfig`

type: (newConfig: StarlightUserConfig) => void

Eine Rückruffunktion zum Aktualisieren des vom Benutzer bereitgestellten Starlight configuration. Geben Sie die Konfigurationsschlüssel auf Stammebene an, die Sie überschreiben möchten. Um verschachtelte Konfigurationswerte zu aktualisieren, müssen Sie das gesamte verschachtelte Objekt bereitstellen.

Um eine vorhandene Konfigurationsoption zu erweitern, ohne sie zu überschreiben, verteilen Sie den vorhandenen Wert in Ihren neuen Wert. Im folgenden Beispiel wird ein neues social-Medienkonto zur vorhandenen Konfiguration hinzugefügt, indem config.social in das neue social-Array verteilt wird:

export default {
  name: 'add-twitter-plugin',
  hooks: {
    'config:setup'({ config, updateConfig }) {
      updateConfig({
        social: [
          ...config.social,
          {
            icon: 'twitter',
            label: 'Twitter',
            href: 'https://twitter.com/astrodotbuild',
          },
        ],
      });
    },
  },
};

`addIntegration`

type: (integration: AstroIntegration) => void

Eine Rückruffunktion zum Hinzufügen eines vom Plugin benötigten Astro integration.

Im folgenden Beispiel prüft das Plugin zunächst, ob Astro’s React integration konfiguriert ist, und wenn nicht, verwendet es addIntegration(), um es hinzuzufügen:

import react from '@astrojs/react';

export default {
  name: 'plugin-using-react',
  hooks: {
    'config:setup'({ addIntegration, astroConfig }) {
      const isReactLoaded = astroConfig.integrations.find(
        ({ name }) => name === '@astrojs/react'
      );

      // Only add the React integration if it's not already loaded.
      if (!isReactLoaded) {
        addIntegration(react());
      }
    },
  },
};

`addRouteMiddleware`

type: (config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void

Eine Rückruffunktion zum Hinzufügen eines route middleware handler zur Site.

Die Eigenschaft entrypoint muss ein Modulspezifizierer für die Middleware-Datei Ihres Plugins sein, die einen onRequest-Handler exportiert.

Im folgenden Beispiel fügt ein als @example/starlight-plugin veröffentlichtes Plugin mithilfe eines npm-Modulspezifizierers eine Routen-Middleware hinzu:

export default {
  name: '@example/starlight-plugin',
  hooks: {
    'config:setup'({ addRouteMiddleware }) {
      addRouteMiddleware({
        entrypoint: '@example/starlight-plugin/route-middleware',
      });
    },
  },
};

Controlling execution order

Standardmäßig wird die Plugin-Middleware in der Reihenfolge ausgeführt, in der die Plugins hinzugefügt werden.

Verwenden Sie die optionale Eigenschaft order, wenn Sie mehr Kontrolle darüber benötigen, wann Ihre Middleware ausgeführt wird. Set order: "pre" to run before a user’s middleware. Set order: "post" to run after all other middleware.

Wenn zwei Plugins Middleware mit demselben order-Wert hinzufügen, wird das zuerst hinzugefügte Plugin zuerst ausgeführt.

`astroConfig`

type: AstroConfig

Eine schreibgeschützte Kopie des vom Benutzer bereitgestellten Astro configuration.

`command`

type: 'dev' | 'build' | 'preview'

Der zum Ausführen von Starlight verwendete Befehl:

dev – Projekt wird mit astro dev ausgeführt
build – Projekt wird mit astro build ausgeführt
preview – Projekt wird mit astro preview ausgeführt

`isRestart`

type: boolean

false, wenn der Entwicklungsserver startet, true, wenn ein Neuladen ausgelöst wird. Zu den häufigsten Gründen für einen Neustart gehört, dass ein Benutzer sein astro.config.mjs bearbeitet, während der Entwicklungsserver läuft.

`logger`

type: AstroIntegrationLogger

Eine Instanz von Astro integration logger, die Sie zum Schreiben von Protokollen verwenden können. Allen protokollierten Nachrichten wird der Plugin-Name vorangestellt.

export default {
  name: 'long-process-plugin',
  hooks: {
    'config:setup'({ logger }) {
      logger.info('Starting long process…');
      // Some long process…
    },
  },
};

Im obigen Beispiel wird eine Nachricht protokolliert, die die bereitgestellte Infonachricht enthält:

[long-process-plugin] Starting long process…

`useTranslations`

type: (lang: string) => I18nT

Rufen Sie useTranslations() mit einem BCP-47-Sprachtag auf, um eine Dienstprogrammfunktion zu generieren, die Zugriff auf UI-Zeichenfolgen für diese Sprache bietet. useTranslations() gibt ein Äquivalent der Astro.locals.t()-API zurück, die in Astro-Komponenten verfügbar ist. Weitere Informationen zu den verfügbaren APIs finden Sie im “Using UI translations”-Handbuch.

export default {
  name: 'plugin-use-translations',
  hooks: {
    'config:setup'({ useTranslations, logger }) {
      const t = useTranslations('zh-CN');
      logger.info(t('builtWithStarlight.label'));
    },
  },
};

Im obigen Beispiel wird eine Nachricht protokolliert, die eine integrierte UI-Zeichenfolge für die Sprache Vereinfachtes Chinesisch enthält:

[plugin-use-translations] 基于 Starlight 构建

`absolutePathToLang`

type: (path: string) => string

Rufen Sie absolutePathToLang() mit einem absoluten Dateipfad auf, um die Sprache für diese Datei abzurufen.

Dies kann besonders nützlich sein, wenn remark or rehype plugins hinzugefügt wird, um Markdown- oder MDX-Dateien zu verarbeiten. Der von diesen Plugins verwendete virtual file format enthält den absolute path der verarbeiteten Datei, der mit absolutePathToLang() verwendet werden kann, um die Sprache der Datei zu bestimmen. Die zurückgegebene Sprache kann mit dem Hilfsprogramm useTranslations() verwendet werden, um UI-Zeichenfolgen für diese Sprache abzurufen.

Zum Beispiel bei der folgenden Starlight-Konfiguration:

starlight({
  title: 'My Docs',
  defaultLocale: 'en',
  locales: {
    // English docs in `src/content/docs/en/`
    en: { label: 'English' },
    // French docs in `src/content/docs/fr/`
    fr: { label: 'Français', lang: 'fr' },
  },
});

Ein Plugin kann die Sprache einer Datei anhand ihres absoluten Pfads ermitteln:

export default {
  name: 'plugin-use-translations',
  hooks: {
    'config:setup'({ absolutePathToLang, useTranslations, logger }) {
      const lang = absolutePathToLang(
        '/absolute/path/to/project/src/content/docs/fr/index.mdx'
      );
      const t = useTranslations(lang);
      logger.info(t('aside.tip'));
    },
  },
};

Im obigen Beispiel wird eine Nachricht protokolliert, die eine integrierte UI-Zeichenfolge für die französische Sprache enthält:

[plugin-use-translations] Astuce