Pular para o conteúdo

Referência do Frontmatter

Você pode customizar páginas Markdown e MDX no Starlight definindo valores em seu frontmatter. Por exemplo, uma página comum pode definir os campos title e description:

src/content/docs/exemplo.md
---
title: Sobre este projeto
description: Aprenda mais sobre o projeto no qual estou trabalhando.
---
Bem-vindo a página "sobre"!

Campos do Frontmatter

title (obrigatório)

tipo: string

Você deve providenciar um título para cada página. Ele será mostrado no topo da página, em abas do navegador e nos metadados da página.

description

tipo: string

A descrição da página é utilizada para metadados da página e será utilizada por motores de busca e em pré-visualizações em redes sociais.

slug

tipo: string

Sobrescreve o slug da página. Veja “Definindo slugs customizados” na documentação do Astro para mais detalhes.

editUrl

tipo: string | boolean

Sobreescreve a configuração global editLink. Defina como false para desabilitar o link “Editar página” para uma página específica ou providencie uma URL alternativa onde o conteúdo dessa página é editável.

tipo: HeadConfig[]

Você pode adicionar tags adicionais para ao <head> da sua página utilizando o campo frontmatter head. Isso significa que você pode adicionar estilos customizados, metadados ou outras tags a uma única página. Similar a opção global head.

src/content/docs/exemplo.md
---
title: Sobre nós
head:
# Utilize uma tag <title> customizada
- tag: title
content: Título sobre customizado
---

tableOfContents

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

Sobrescreve a configuração global tableOfContents. Customize os níveis de cabeçalho a serem incluídos ou defina como false para esconder o índice nessa página.

src/content/docs/exemplo.md
---
title: Página com apenas H2s no índice
tableOfContents:
minHeadingLevel: 2
maxHeadingLevel: 2
---
src/content/docs/exemplo.md
---
title: Página sem índice
tableOfContents: false
---

template

tipo: 'doc' | 'splash'
padrão: 'doc'

Define o layout de template para essa página. Páginas usam o layout 'doc' por padrão. Defina para 'splash' para usar o layout mais largo sem nenhuma barra lateral, projetado para páginas iniciais.

hero

tipo: HeroConfig

Adiciona um componente hero ao topo dessa página. Funciona bem com template: splash.

Por exemplo, essa configuração mostra algumas opções comuns, incluindo carregamento de uma imagem do seu repositório.

src/content/docs/exemplo.md
---
title: Minha Página Inicial
template: splash
hero:
title: 'Meu Projeto: Coisas Estelares Cedo'
tagline: Leve suas coisas ao espaço e de volta em um piscar de olhos.
image:
alt: Uma logo reluzente e brilhantemente colorida
file: ../../assets/logo.png
actions:
- text: Me diga mais
link: /getting-started/
icon: right-arrow
variant: primary
- text: Veja no GitHub
link: https://github.com/astronaut/meu-projeto
icon: external
attrs:
target: _blank
rel: noopener
---

Você pode exibir diferentes versões da imagem hero no modo claro e escuro.

src/content/docs/exemplo.md
---
hero:
image:
alt: Um logo brilhante e colorido
dark: ../../assets/logo-escuro.png
light: ../../assets/logo-claro.png
---

HeroConfig

interface HeroConfig {
title?: string;
tagline?: string;
image?:
| {
// Caminho relativo de uma imagem no seu repositório.
file: string;
// Texto alternativo para tornar a imagem acessível à tecnologia assistiva
alt?: string;
}
| {
// Caminho relativo de uma imagem em seu repositório para ser usada no modo escuro.
dark: string;
// Caminho relativo de uma imagem em seu repositório para ser usada no modo claro.
light: string;
// Texto alternativo para tornar a imagem acessível à tecnologia assistiva
alt?: string;
}
| {
// HTML bruto para utilizar no slot de imagem.
// Pode ser uma tag `<img>` personalizada ou um `<svg>` inline.
html: string;
};
actions?: Array<{
text: string;
link: string;
variant: 'primary' | 'secondary' | 'minimal';
icon: string;
attrs?: HTMLAttributes<"a">;
}>;
}

tipo: { content: string }

Exibe um banner de anúncio no topo desta página.

O valor de conteúdo pode incluir HTML para links ou outro conteúdo. Por exemplo, esta página exibe um banner que inclui um link para example.com.

src/content/docs/exemplo.md
---
title: Página com um banner
banner:
content: |
Acabamos de lançar algo legal!
<a href="https://example.com">Confira</a>
---

lastUpdated

tipo: Date | boolean

Sobrescreve a opção global lastUpdated. Se uma data é especificada, ela deve ser um timestamp YAML válido e irá sobrescrever a data armazenada no histórico do Git para essa página.

src/content/docs/exemplo.md
---
title: Página com uma data de última atualização customizada
lastUpdated: 2022-08-09
---

prev

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

Sobrescreve a opção global pagination. Se uma string é especificada, o texto do link gerado será substituído e se um objeto for especificado, ambos o link e o texto serão sobrescritos.

src/content/docs/exemplo.md
---
# Esconda o link da página anterior
prev: false
---
src/content/docs/exemplo.md
---
# Sobrescreva o texto do link da página anterior
prev: Continue o tutorial
---
src/content/docs/exemplo.md
---
# Sobrescreva ambos o link e o texto da página anterior
prev:
link: /pagina-diferente/
label: Veja essa outra página
---

next

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

Mesmo que prev mas para o link da próxima página.

src/content/docs/exemplo.md
---
# Esconda o link da próxima página
next: false
---

pagefind

tipo: boolean
padrão: true

Configura se essa página deve ou não ser inclusa no índice de busca do Pagefind. Defina como false para excluir a página do resultado de buscas.

src/content/docs/exemplo.md
---
# Não exibir essa página nas buscas
pagefind: false
---

tipo: SidebarConfig

Controla como essa página é mostrada na barra lateral, quando se utiliza um grupo de links gerados automaticamente.

SidebarConfig

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

label

tipo: string
padrão: title da página

Define o rótulo para essa página na barra lateral quando mostrado em um grupo de links gerados automaticamente.

src/content/docs/exemplo.md
---
title: Sobre este projeto
sidebar:
label: Sobre
---

order

tipo: number

Controla a ordem dessa página ao ordenar um grupo de links gerados automaticamente. Números menores são mostrados acima no grupo de links.

src/content/docs/exemplo.md
---
title: Página para mostrar primeiro
sidebar:
order: 1
---

hidden

tipo: boolean padrão: false

Previne essa página de ser incluída no no grupo gerado automaticamente da barra lateral.

src/content/docs/exemplo.md
---
title: Página para esconder da barra lateral gerada automaticamente
sidebar:
hidden: true
---

badge

type: string | BadgeConfig

Adicione um emblema a página na barra lateral ao ser mostrada em um grupo gerado automaticamente de links. Ao utilizar uma string, o emblema será mostrado com uma cor de destaque padrão. Opcionalmente, passe um objeto BadgeConfig com os campos text e variant para customizar o emblema.

src/content/docs/exemplo.md
---
title: Página com um emblema
sidebar:
# Utiliza a variante padrão correspondente a cor de destaque do seu site
badge: New
---
src/content/docs/exemplo.md
---
title: Página com um emblema
sidebar:
badge:
text: Experimental
variant: caution
---

attrs

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

Atributos HTML que será adicionado ao link da barra lateral da página quando exibido em um grupo de link gerados automaticamente.

src/content/docs/exemplo.md
---
title: Abrir em nova aba
sidebar:
# Abre a página em uma nova aba
attrs:
target: _blank
---

Customize o esquema de frontmatter

O esquema de frontmatter da coleção de conteúdo docs do Starlight é configurado em src/content/config.ts utilizando o utilitário docsSchema():

src/content/config.ts
import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ schema: docsSchema() }),
};

Aprenda mais sobre esquemas de coleções de conteúdo em “Definindo um esquema de coleção” na documentação do Astro.

docsSchema() recebe os seguintes argumentos:

extend

tipo: Esquema do Zod ou função que retorne um esquema do Zod
padrão: z.object({})

Estenda o esquema do Starlight com campos adicionais definindo extend nas opções do docsSchema(). O valor deve ser um esquema do Zod.

No exemplo a seguir, nós definimos um tipo mais restrito para a descrição (description) para torná-la obrigatória e adicionamos um novo campo opcional categoria:

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({
// Torna um campo nativo obrigatório ao invés de opcional.
description: z.string(),
// Adiciona um novo campo ao esquema.
categoria: z.enum(['tutorial', 'guia', 'referência']).optional(),
}),
}),
}),
};

Para fazer uso do utilitário image() do Astro, use uma função para retornar sua extensão de esquema:

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({
// Adiciona um campo que deve resolver para uma imagem local.
cover: image(),
});
},
}),
}),
};