Lewati ke konten
Starlight

Referensi Frontmatter

Anda dapat menyesuaikan masing-masing halaman Markdown dan MDX di Starlight dengan menetapkan nilai di frontmatter. Sebagai contoh, halaman biasa dapat mengatur bidang title dan description:

src/content/docs/example.md
---
title: Tentang proyek ini
description: Pelajari lebih lanjut tentang proyek yang sedang Saya kerjakan.
---


Selamat datang di halaman Tentang!

Bidang Frontmatter

title (diperlukan)

tipe: string

Anda harus memberikan judul untuk setiap halaman. Ini akan ditampilkan di bagian atas halaman, di tab browser, dan di metadata halaman.

description

tipe: string

Deskripsi halaman digunakan untuk metadata halaman dan akan diambil oleh mesin pencari dan dalam pratinjau media sosial.

slug

tipe: string

Ganti slug halaman. Lihat “Mendefinisikan slug khusus” di dokumentasi Astro untuk detail lebih lanjut.

editUrl

tipe: string | boolean

Mengesampingkan konfigurasi editLink global. Atur ke false untuk menonaktifkan tautan “Edit halaman” untuk halaman tertentu atau memberikan URL alternatif di mana konten halaman ini dapat diedit.

tipe: HeadConfig[]

Anda dapat menambahkan tag tambahan ke <head> halaman Anda menggunakan bidang head frontmatter. Ini berarti Anda dapat menambahkan gaya khusus, metadata, atau tag lain ke satu halaman. Mirip dengan opsi head global.

src/content/docs/example.md
---
title: Tentang kami
head:
  # Gunakan tag <title> khusus
  - tag: title
    content: Halaman tentang khusus
---

tableOfContents

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

Mengesampingkan konfigurasi tableOfContents global. Sesuaikan tingkat judul yang akan disertakan atau atur ke false untuk menyembunyikan daftar isi pada halaman ini.

src/content/docs/example.md
---
title: Halaman dengan hanya H2 dalam daftar isi
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---
src/content/docs/example.md
---
title: Halaman tanpa daftar isi
tableOfContents: false
---

template

tipe: 'doc' | 'splash'
bawaan: 'doc'

Atur templat tata letak untuk halaman ini. Halaman menggunakan tata letak 'doc' secara default. Atur ke 'splash' untuk menggunakan tata letak yang lebih lebar tanpa sidebar yang dirancang untuk landing pages.

hero

tipe: HeroConfig

Tambahkan komponen hero ke bagian atas halaman ini. Berfungsi dengan baik dengan template: splash.

Sebagai contoh, konfigurasi ini menampilkan beberapa opsi umum, termasuk memuat gambar dari repositori Anda.

src/content/docs/example.md
---
title: Halaman Beranda Saya
template: splash
hero:
  title: 'Proyek Saya: Stellar Stuff Sooner'
  tagline: Bawa barang-barang Anda ke bulan dan kembali dalam sekejap mata.
  image:
    alt: Logo yang berkilauan dan berwarna cerah
    file: ../../assets/logo.png
  actions:
    - text: Ceritakan lebih banyak
      link: /getting-started/
      icon: right-arrow
    - text: Lihat di GitHub
      link: https://github.com/astronaut/my-project
      icon: external
      variant: minimal
      attrs:
        rel: me
---

Anda dapat menampilkan versi gambar hero yang berbeda dalam mode terang dan gelap.

src/content/docs/example.md
---
hero:
  image:
    alt: Logo yang berkilauan dan berwarna cerah
    dark: ~/assets/logo-dark.png
    light: ~/assets/logo-light.png
---

HeroConfig

interface HeroConfig {
  title?: string;
  tagline?: string;
  image?:
    | {
        // Path relatif ke gambar di repositori Anda.
        file: string;
        // Teks alternatif untuk membuat gambar dapat diakses oleh teknologi bantu
        alt?: string;
      }
    | {
        // Path relatif ke gambar di repositori Anda yang akan digunakan untuk mode gelap.
        dark: string;
        // Path relatif ke gambar di repositori Anda yang akan digunakan untuk mode terang.
        light: string;
        // Teks alternatif untuk membuat gambar dapat diakses oleh teknologi bantu
        alt?: string;
      }
    | {
        // HTML mentah (raw) untuk digunakan dalam slot gambar.
        // Bisa berupa tag `<img>` khusus atau tag `<svg>` sebaris.
        html: string;
      };
  actions?: Array<{
    text: string;
    link: string;
    variant?: 'primary' | 'secondary' | 'minimal';
    icon?: string;
    attrs?: Record<string, string | number | boolean>;
  }>;
}

tipe: { content: string }

Menampilkan banner pengumuman di bagian atas halaman ini.

Nilai content dapat berupa HTML untuk tautan atau konten lainnya. Sebagai contoh, halaman ini menampilkan spanduk yang menyertakan tautan ke example.com.

src/content/docs/example.md
---
title: Halaman dengan banner
banner:
  content: |
    Kami baru saja meluncurkan sesuatu yang keren!
    <a href="https://example.com">Lihatlah</a>
---

lastUpdated

tipe: Date | boolean

Mengesampingkan opsi lastUpdated global. Jika tanggal ditentukan, tanggal tersebut harus berupa stempel waktu YAML yang valid dan akan menimpa tanggal yang tersimpan dalam riwayat Git untuk halaman ini.

src/content/docs/example.md
---
title: Halaman dengan tanggal pembaruan terakhir khusus
lastUpdated: 2022-08-09
---

prev

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

Mengesampingkan opsi pagination global. Jika string ditentukan, teks tautan yang dihasilkan akan diganti dan jika objek ditentukan, tautan dan teks akan ditimpa.

src/content/docs/example.md
---
# Menyembunyikan tautan halaman sebelumnya
prev: false
---
src/content/docs/example.md
---
# Mengganti teks tautan halaman sebelumnya
prev: lanjutkan tutorial
---
src/content/docs/example.md
---
# Mengabaikan tautan dan teks halaman sebelumnya
prev:
  link: /halaman-yang-tidak-berkaitkan/
  label: Lihat halaman lainnya
---

next

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

Sama seperti prev tetapi untuk tautan halaman berikutnya.

src/content/docs/example.md
---
# Menyembunyikan tautan halaman berikutnya
next: false
---

pagefind

tipe: boolean
bawaan: true

Mengatur apakah halaman ini harus disertakan dalam indeks pencarian Pagefind. Atur ke false untuk mengecualikan halaman dari hasil pencarian:

src/content/docs/example.md
---
# Sembunyikan halaman ini dari indeks pencarian
pagefind: false
---

draft

tipe: boolean
bawaan: false

Tetapkan apakah halaman ini harus dianggap sebagai draf dan tidak disertakan dalam versi produksi dan grup tautan yang dibuat secara otomatis. Ubah ke true untuk menandai halaman sebagai draf dan membuatnya hanya terlihat selama masa pengembangan.

src/content/docs/example.md
---
# Kecualikan halaman ini dari versi produksi
draft: true
---

tipe: SidebarConfig

Mengontrol bagaimana halaman ini ditampilkan di sidebar, saat menggunakan grup tautan yang dibuat secara otomatis.

SidebarConfig

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

label

tipe: string
bawaan: title halaman

Atur label untuk halaman ini di sidebar saat ditampilkan dalam grup tautan yang dibuat secara otomatis.

src/content/docs/example.md
---
title: Tentang proyek ini
sidebar:
  label: Tentang
---

order

tipe: number

Mengontrol urutan halaman ini saat mengurutkan grup tautan yang dibuat secara otomatis. Nomor yang lebih rendah ditampilkan lebih tinggi dalam grup tautan.

src/content/docs/example.md
---
title: Halaman yang akan ditampilkan pertama kali
sidebar:
  order: 1
---

hidden

tipe: boolean
bawaan: false

Mencegah halaman ini disertakan dalam grup sidebar yang dibuat secara otomatis.

src/content/docs/example.md
---
title: Halaman yang disembunyikan dari sidebar yang dibuat secara otomatis
sidebar:
  hidden: true
---

badge

tipe: string | BadgeConfig

Menambahkan badge ke halaman di sidebar saat ditampilkan dalam grup tautan yang dibuat secara otomatis. Saat menggunakan string, badge akan ditampilkan dengan warna aksen bawaan. Secara opsional, berikan objek BadgeConfig dengan bidang text, variant, dan class untuk menyesuaikan badge.

src/content/docs/example.md
---
title: Halaman dengan badge
sidebar:
  # Menggunakan varian bawaan yang sesuai dengan warna aksen situs Anda
  badge: Baru
---
src/content/docs/example.md
---
title: Halaman badge
sidebar:
  badge:
    text: Eksperimental
    variant: caution
---

attrs

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

Atribut HTML untuk ditambahkan ke tautan halaman di sidebar saat ditampilkan dalam grup tautan yang dibuat secara otomatis.

src/content/docs/example.md
---
title: Membuka halaman di tab baru
sidebar:
  # Membuka halaman di tab baru
  attrs:
    target: _blank
---

Sesuaikan skema frontmatter

Skema frontmatter untuk koleksi konten docs Starlight dikonfigurasikan dalam src/content/config.ts menggunakan helper docsSchema():

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


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

Pelajari selengkapnya tentang koleksi skema konten di “Mendefinisikan koleksi skema” di dokumentasi Astro.

docsSchema() memiliki opsi berikut:

extend

tipe: Skema Zod atau fungsi yang mengembalikan skema Zod
bawaan: z.object({})

Pengembangan skema Starlight dengan kolom tambahan dengan menyetel extend dalam opsi docsSchema(). Nilainya harus berupa skema Zod.

Dalam contoh berikut, kami menyediakan tipe yang lebih ketat untuk description agar menjadi wajib dan menambahkan kolom category opsional baru:

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({
        // Jadikan kolom bawaan sebagai wajib, bukan opsional.
        description: z.string(),
        // Tambahkan kolom baru ke skema.
        category: z.enum(['tutorial', 'guide', 'reference']).optional(),
      }),
    }),
  }),
};

Untuk memanfaatkan Astro image() helper, gunakan fungsi yang mengembalikan ekstensi skema Anda:

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({
          // Tambahkan kolom yang harus dilengkapi ke gambar lokal.
          cover: image(),
        });
      },
    }),
  }),
};