コンテンツにスキップ
Starlight
Filters

    フロントマター

    Starlightでは、フロントマターに値を設定することで、MarkdownとMDXのページを個別にカスタマイズできます。たとえば通常のページでは、titleとdescriptionフィールドを設定します。

    src/content/docs/example.md
    ---
    title: このプロジェクトについて
    description: 私が取り組んでいるプロジェクトについてもっと知る。
    ---
    

    概要ページへようこそ！

    フロントマターのフィールド

    Section titled “フロントマターのフィールド”

    title（必須）

    Section titled “title（必須）”

    type: string

    すべてのページにタイトルを指定する必要があります。これは、ページの上部、ブラウザのタブ、およびページのメタデータとして表示されます。

    description

    Section titled “description”

    type: string

    ページに関する説明文はページのメタデータとして使用され、また検索エンジンやソーシャルメディアのプレビューでも使用されます。

    slug

    Section titled “slug”

    type: string

    ページのスラグを上書きします。詳しくは、Astroドキュメントの「カスタムスラグの定義」を参照してください。

    editUrl

    Section titled “editUrl”

    type: string | boolean

    グローバルの editLink 設定を上書きします。falseを設定して特定のページの「ページを編集」リンクを無効にするか、あるいはこのページのコンテンツを編集する代替URLを指定します。

    Section titled “head”

    type: HeadConfig[]

    フロントマターのheadフィールドを使用して、ページの<head>にタグを追加できます。これにより、カスタムスタイル、メタデータ、またはその他のタグを単一のページに追加できます。グローバルのheadオプションと同様です。

    src/content/docs/example.md
    ---
    title: 私たちについて
    head:
      # カスタム<title>タグを使う
      - tag: title
        content: カスタムのタイトル
    ---

    tableOfContents

    Section titled “tableOfContents”

    type: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }

    グローバルのtableOfContents設定を上書きします。表示したい見出しのレベルをカスタマイズするか、あるいはfalseに設定して目次を非表示とします。

    src/content/docs/example.md
    ---
    title: 目次にH2のみを表示するページ
    tableOfContents:
      minHeadingLevel: 2
      maxHeadingLevel: 2
    ---
    src/content/docs/example.md
    ---
    title: 目次のないページ
    tableOfContents: false
    ---

    template

    Section titled “template”

    type: 'doc' | 'splash'
    default: 'doc'

    ページのレイアウトテンプレートを設定します。ページはデフォルトで'doc'レイアウトを使用します。ランディングページ向けにサイドバーのない幅広のレイアウトを使用するには、'splash'を設定します。

    hero

    Section titled “hero”

    type: HeroConfig

    ヒーローコンポーネントをページの上部に追加します。template: splashとの相性が良いでしょう。

    リポジトリからの画像の読み込みなど、よく使われるオプションの設定例は以下となります。

    src/content/docs/example.md
    ---
    title: 私のホームページ
    template: splash
    hero:
      title: '私のプロジェクト: 最高品質を、最速で'
      tagline: 瞬く間に月まで一往復。
      image:
        alt: キラリと光る、鮮やかなロゴ
        file: ../../assets/logo.png
      actions:
        - text: もっと知りたい
          link: /getting-started/
          icon: right-arrow
        - text: GitHubで見る
          link: https://github.com/astronaut/my-project
          icon: external
          variant: minimal
          attrs:
            rel: me
    ---

    ライトモードとダークモードで、異なるバージョンのヒーロー画像を表示できます。

    src/content/docs/example.md
    ---
    hero:
      image:
        alt: キラリと光る、鮮やかなロゴ
        dark: ../../assets/logo-dark.png
        light: ../../assets/logo-light.png
    ---

    HeroConfig

    Section titled “HeroConfig”
    interface HeroConfig {
      title?: string;
      tagline?: string;
      image?:
        | {
            // リポジトリ内の画像への相対パス。
            file: string;
            // この画像を支援技術からアクセス可能にするための代替テキスト。
            alt?: string;
          }
        | {
            // ダークモードで使用する、リポジトリ内の画像への相対パス。
            dark: string;
            // ライトモードで使用する、リポジトリ内の画像への相対パス。
            light: string;
            // この画像を支援技術からアクセス可能にするための代替テキスト。
            alt?: string;
          }
        | {
            // 画像のスロットに使用する生のHTML。
            // カスタムの`<img>`タグやインラインの`<svg>`などが使えます。
            html: string;
          };
      actions?: Array<{
        text: string;
        link: string;
        variant?: 'primary' | 'secondary' | 'minimal';
        icon?: string;
        attrs?: Record<string, string | number | boolean>;
      }>;
    }
    Section titled “banner”

    type: { content: string }

    ページの上部にお知らせ用のバナーを表示します。

    contentの値には、リンクやその他のコンテンツ用のHTMLを含められます。たとえば以下のページでは、example.comへのリンクを含むバナーを表示しています。

    src/content/docs/example.md
    ---
    title: バナーを含むページ
    banner:
      content: |
        素晴らしいサイトをリリースしました！
        <a href="https://example.com">確認してみてください</a>
    ---

    lastUpdated

    Section titled “lastUpdated”

    type: Date | boolean

    グローバルのlastUpdatedオプションを上書きします。日付を指定する場合は有効なYAMLタイムスタンプである必要があり、ページのGit履歴に保存されている日付を上書きします。

    src/content/docs/example.md
    ---
    title: 最終更新日をカスタマイズしたページ
    lastUpdated: 2022-08-09
    ---

    prev

    Section titled “prev”

    type: boolean | string | { link?: string; label?: string }

    グローバルのpaginationオプションを上書きします。文字列を指定すると生成されるリンクテキストが置き換えられ、オブジェクトを指定するとリンクとテキストの両方を上書きできます。

    src/content/docs/example.md
    ---
    # 前のページへのリンクを非表示にする
    prev: false
    ---
    src/content/docs/example.md
    ---
    # 前のページへのリンクテキストを上書きする
    prev: チュートリアルを続ける
    ---
    src/content/docs/example.md
    ---
    # 前のページへのリンクとテキストを上書きする
    prev:
      link: /unrelated-page/
      label: その他のページをチェックする
    ---

    next

    Section titled “next”

    type: boolean | string | { link?: string; label?: string }

    次のページへのリンクに対して、prevと同様の設定ができます。

    src/content/docs/example.md
    ---
    # 次のページへのリンクを非表示にする
    next: false
    ---

    pagefind

    Section titled “pagefind”

    type: boolean
    default: true

    ページをPagefindの検索インデックスに含めるかどうかを設定します。ページを検索結果から除外するには、falseに設定します。

    src/content/docs/example.md
    ---
    # このページを検索インデックスから外す
    pagefind: false
    ---

    draft

    Section titled “draft”

    type: boolean
    default: false

    このページをドラフトとしてマークし、本番ビルドと自動生成されるリンクのグループから除外するかどうかを設定します。ページをドラフトとしてマークし、開発中にのみ表示するにはtrueに設定します。

    src/content/docs/example.md
    ---
    # 本番ビルドからこのページを除外します
    draft: true
    ---
    Section titled “sidebar”

    type: SidebarConfig

    自動生成されるリンクのグループを使用している際に、サイドバーにページをどのように表示するかを設定します。

    SidebarConfig

    Section titled “SidebarConfig”
    interface SidebarConfig {
      label?: string;
      order?: number;
      hidden?: boolean;
      badge?: string | BadgeConfig;
      attrs?: Record<string, string | number | boolean | undefined>;
    }

    label

    Section titled “label”

    type: string
    default: ページのtitle

    自動生成されるリンクのグループ内に表示される、ページのサイドバー上でのラベルを設定します。

    src/content/docs/example.md
    ---
    title: このプロジェクトについて
    sidebar:
      label: 概要
    ---

    order

    Section titled “order”

    type: number

    自動生成されるリンクのグループをソートする際の、このページの順番を設定します。小さな数値ほどリンクグループの上部に表示されます。

    src/content/docs/example.md
    ---
    title: 最初に表示するページ
    sidebar:
      order: 1
    ---

    hidden

    Section titled “hidden”

    type: boolean default: false

    自動生成されるサイドバーのグループにこのページを含めないようにします。

    src/content/docs/example.md
    ---
    title: 自動生成されるサイドバーで非表示にするページ
    sidebar:
      hidden: true
    ---

    badge

    Section titled “badge”

    type: string | BadgeConfig

    自動生成されるリンクのグループに表示されたとき、サイドバーのページにバッジを追加します。文字列を使用すると、バッジはデフォルトのアクセントカラーで表示されます。オプションで、textとvariant、classフィールドをもつBadgeConfigオブジェクトを渡してバッジをカスタマイズできます。

    src/content/docs/example.md
    ---
    title: バッジを含むページ
    sidebar:
      # サイトのアクセントカラーに合わせたデフォルトのバリアントを使用します
      badge: New
    ---
    src/content/docs/example.md
    ---
    title: バッジを含むページ
    sidebar:
      badge:
        text: 実験的
        variant: caution
    ---

    attrs

    Section titled “attrs”

    type: Record<string, string | number | boolean | undefined>

    自動生成されるリンクのグループ内に表示されるサイドバーのページリンクに追加するHTML属性。

    src/content/docs/example.md
    ---
    title: 新しいタブで開くページ
    sidebar:
      # 新しいタブでページを開きます
      attrs:
        target: _blank
    ---

    フロントマタースキーマをカスタマイズする

    Section titled “フロントマタースキーマをカスタマイズする”

    Starlightのdocsコンテンツコレクションのフロントマタースキーマは、docsSchema()ヘルパーを使用してsrc/content/config.tsで設定されています。

    src/content/config.ts
    import { defineCollection } from 'astro:content';
    import { docsSchema } from '@astrojs/starlight/schema';
    

    export const collections = {
      docs: defineCollection({ schema: docsSchema() }),
    };

    コンテンツコレクションのスキーマについて詳しくは、Astroドキュメントの「コレクションスキーマの定義」を参照してください。

    docsSchema()は以下のオプションを受け取ります。

    extend

    Section titled “extend”

    type: ZodスキーマまたはZodスキーマを返す関数
    default: z.object({})

    docsSchema()のオプションでextendを設定すると、Starlightのスキーマを追加のフィールドで拡張できます。値はZodスキーマである必要があります。

    次の例では、descriptionを必須にするために厳し目の型を指定し、さらにオプションのcategoryフィールドを新規追加しています。

    src/content/config.ts
    import { defineCollection, z } from 'astro:content';
    import { docsSchema } from '@astrojs/starlight/schema';
    

    export const collections = {
      docs: defineCollection({
        schema: docsSchema({
          extend: z.object({
            // 組み込みのフィールドをオプションから必須に変更します。
            description: z.string(),
            // 新しいフィールドをスキーマに追加します。
            category: z.enum(['tutorial', 'guide', 'reference']).optional(),
          }),
        }),
      }),
    };

    Astroのimage()ヘルパーを利用するには、拡張したスキーマを返す関数を使用します。

    src/content/config.ts
    import { defineCollection, z } from 'astro:content';
    import { docsSchema } from '@astrojs/starlight/schema';
    

    export const collections = {
      docs: defineCollection({
        schema: docsSchema({
          extend: ({ image }) => {
            return z.object({
              // ローカルの画像へと解決されるフィールドを追加します。
              cover: image(),
            });
          },
        }),
      }),
    };