コンテンツにスキップ
Theme

Astro 設定

コンテンツリポジトリは独自の astro.config.mjs を保持しません。代わりに、@f5-sales-demo/docs-theme npm パッケージから設定ファクトリーをインポートし、Starlight、8つのバンドルプラグイン、およびすべてのテーマデフォルトを含む完全な Astro 設定を返します。

テーマの利用

Section titled “テーマの利用”

コンテンツリポジトリの astro.config.mjs（Docker ビルダーによって提供）は薄いラッパーです:

import { createF5xcDocsConfig } from '@f5-sales-demo/docs-theme/config';


export default createF5xcDocsConfig();

すべてのカスタマイズはオプションオブジェクトまたは環境変数を通じて行われます — プラグインの配線、CSS インポート、またはコンポーネントのオーバーライドを直接操作する必要はありません。

設定オプション

Section titled “設定オプション”

createF5xcDocsConfig は F5xcDocsConfigOptions オブジェクトを受け付けます。すべてのフィールドはオプションであり、環境変数と適切なデフォルト値が不足分を補います。

interface F5xcDocsConfigOptions {
  site?: string;
  base?: string;
  title?: string;
  description?: string;
  githubRepository?: string;
  llmsOptionalLinks?: Array<{ title: string; url: string }>;
  additionalIntegrations?: AstroIntegration[];
  additionalRemarkPlugins?: Array<unknown>;
  megaMenuItems?: MegaMenuItem[];
  head?: HeadEntry[];
  logo?: { src: string } | { light: string; dark: string };
}
オプションデフォルト / 環境変数フォールバック用途
siteDOCS_SITE または https://f5-sales-demo.github.io正規ベース URL
baseDOCS_BASE または /プロジェクトサイト用の URL ベースパス
titleDOCS_TITLE または Documentationヘッダーおよびブラウザタブのサイトタイトル
descriptionDOCS_DESCRIPTION または空文字列メタデータおよび llms.txt 用のサイト説明
githubRepositoryGITHUB_REPOSITORY または空文字列編集リンクと GitHub ソーシャルアイコンを有効化
llmsOptionalLinksLLMS_OPTIONAL_LINKS (JSON) または []llms.txt プラグイン用の追加リンク
additionalIntegrations[]追加で付加する Astro インテグレーション
additionalRemarkPlugins[]remark-mermaid の後に追加される追加 remark プラグイン
megaMenuItems組み込みの Products/Solutions/Docs/Support メニュートップレベルのメガメニューエントリー
headMermaid CDN <script> タグカスタム <head> エントリー
logo@f5-sales-demo/docs-theme/assets/github-avatar.pngサイドバーロゴ（単一の src またはライト/ダークペア）

バンドルされた Starlight プラグイン

Section titled “バンドルされた Starlight プラグイン”

ファクトリーは 8 つの Starlight プラグインを自動的に配線します:

プラグイン用途
starlight-mega-menuグリッド/リストレイアウトのトップナビゲーションメガメニュー
starlight-videosドキュメントページへの動画埋め込み
starlight-image-zoom画像のクリックズーム
@f5-sales-demo/docs-theme（自身）CSS インジェクション、コンポーネントオーバーライド、ルートミドルウェア
starlight-scroll-to-topプログレスリング付きのスクロールトップボタン
starlight-heading-badges見出しへのバッジアノテーション
starlight-page-actionsページアクションボタン
starlight-plugin-iconsStarlight でのアイコンサポート
starlight-llms-txtLLM 利用向けに llms.txt および llms-full.txt を生成

これらは config.ts 内で順番に登録されます。テーマプラグイン（@f5-sales-demo/docs-theme）自体がこのリスト内で実行される Starlight プラグインです。

テーマプラグインフック

Section titled “テーマプラグインフック”

テーマプラグインは index.ts で定義され、上記のバンドルプラグインの中に登録されます。その config:setup フックは 3 つのことを行います:

  1. CSS のインジェクション — fonts/font-face.css と styles/custom.css を Starlight の customCss 配列の先頭に追加
  2. コンポーネントのオーバーライド — 5 つの Starlight コンポーネントを置き換え:
    • Banner — 編集リンク付きのパンくずナビゲーション
    • EditLink — 意図的に空（編集リンクは Banner 内に存在）
    • Footer — デフォルトフッターの下にソーシャルメディアリンクを追加
    • SiteTitle — ホームリンク付きロゴ
    • MarkdownContent — 動画と画像ズームを有効にするラッパー
  3. ルートミドルウェアの追加 — インデックスページをサイドバーからフィルタリングし、インデックスページの目次を非表示にする route-middleware.ts を登録
// index.ts — Starlight plugin entry point
export default function f5xcDocsTheme(): StarlightPlugin {
  return {
    name: '@f5-sales-demo/docs-theme',
    hooks: {
      'config:setup'({ config, updateConfig, addRouteMiddleware }) {
        addRouteMiddleware({
          entrypoint: '@f5-sales-demo/docs-theme/route-middleware',
          order: 'pre',
        });
        updateConfig({
          customCss: [
            ...(config.customCss ?? []),
            '@f5-sales-demo/docs-theme/fonts/font-face.css',
            '@f5-sales-demo/docs-theme/styles/custom.css',
          ],
          components: {
            ...config.components,
            Banner: '@f5-sales-demo/docs-theme/components/Banner.astro',
            EditLink: '@f5-sales-demo/docs-theme/components/EditLink.astro',
            Footer: '@f5-sales-demo/docs-theme/components/Footer.astro',
            SiteTitle: '@f5-sales-demo/docs-theme/components/SiteTitle.astro',
            MarkdownContent: '@f5-sales-demo/docs-theme/components/MarkdownContent.astro',
          },
        });
      },
    },
  };
}

すべてのパスは npm パッケージ指定子（例: @f5-sales-demo/docs-theme/styles/custom.css）を使用しており、package.json の exports マップを通じて解決されます。

その他のインテグレーション

Section titled “その他のインテグレーション”

Starlight とそのプラグインに加えて、ファクトリーは次のものも登録します:

  • @astrojs/react — MDX ページでの React コンポーネントサポートを有効化
  • remark-mermaid — ```mermaid コードブロックをレンダリングされたダイアグラムに変換するカスタム remark プラグイン

追加のインテグレーションと remark プラグインは、additionalIntegrations および additionalRemarkPlugins オプションを通じて付加できます。

サイドバー

Section titled “サイドバー”

カスタムサイドバーは定義されていません。Starlight は docs/ のファイル構造からサイドバーを自動生成し、各ページの title フロントマターをリンクテキストとして使用し、sidebar.order でソートします。ルートミドルウェアはインデックスページをサイドバーから自動的にフィルタリングします。