Referência da Configuração
Configure a integração starlight
Starlight é uma integração construída em cima do framework web Astro. Você pode configurar o seu projeto dentro do arquivo de configuração astro.config.mjs
:
Você pode passar as seguintes opções para a integração starlight
.
title
(obrigatório)
tipo: string
Define o título do seu site. Será usado em metadados e no título da aba do navegador.
description
tipo: string
Define a descrição do seu website. Usado em metadados compartilhados com motores de busca na tag <meta name="description">
se description
não for definido no frontmatter de uma página.
logo
tipo: LogoConfig
Define a imagem da logo a ser mostrada na barra de navegação ao lado ou no lugar do título da página. Você pode definir uma única propriedade src
ou definir fontes de imagem separadas para os modos light
e dark
.
LogoConfig
tableOfContents
tipo: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }
padrão: { minHeadingLevel: 2; maxHeadingLevel: 3; }
Configura o índice mostrado a direita de cada página. Por padrão, cabeçalhos <h2>
e <h3>
serão incluídos no índice.
editLink
tipo: { baseUrl: string }
Habilita links “Editar página” definindo a URL base que deve ser utilizada. O link final será editLink.baseUrl
+ o caminho da página atual. Por exemplo, para habilitar editar páginas no repositório withastro/starlight
no GitHub:
Com essa configuração, uma página /introducao
teria um link de edição apontando para https://github.com/withastro/starlight/edit/main/src/content/docs/introducao.md
.
sidebar
tipo: SidebarItem[]
Configura os itens de navegação da barra lateral do seu site.
Uma barra lateral é um array de links e grupos de links.
Cada item deve ter um label
e uma das seguintes propriedades:
-
link
— um único link para uma URL específica, e.x.'/inicio'
ou'https://exemplo.com'
. -
items
— um array contendo mais links da barra lateral e subgrupos. -
autogenerate
— um objeto especificando um diretório da sua documentação para gerar automaticamente um grupo de links.
Ordenação
Grupos da barra lateral gerados automaticamente são ordenados pelo nome de arquivo alfabeticamente.
Por exemplo, uma página gerada de astro.md
apareceria acima da página de starlight.md
.
Escondendo grupos
Grupos de links são expandidos por padrão. Você pode modificar esse comportamento definindo a propriedade collapsed
de um grupo para true
.
Subgrupos gerados automaticamente respeitam a propriedade collapsed
de seu grupo pai por padrão. Defina a propriedade autogenerate.collapsed
para sobrescrever isso.
Traduzindo rótulos
Se o seu site é multilíngue, a label
de cada item é considerada como estando no seu local padrão. Você pode definir uma propriedade translations
para providenciar rótulos para suas outras línguas suportadas:
SidebarItem
BadgeConfig
locales
tipo: { [dir: string]: LocaleConfig }
Configure internacionalização (i18n) para o seu site definindo quais locales
são suportados.
Cada entrada deve usar o diretório onde os arquivos daquela língua estão salvos como a chave.
LocaleConfig
Você pode definir as seguintes opções para cada local:
label
(obrigatório)
tipo: string
O rótulo para essa língua para mostrar aos usuários, por exemplo no seletor de língua. Geralmente você vai querer que isso seja o nome da língua da forma com que um usuário da língua esperaria lê-lo, e.x. "English"
, "العربية"
ou "简体中文"
.
lang
tipo: string
A tag BCP-47 para essa língua, e.x. "en"
, "ar"
ou "zh-CN"
. Se não definido, o diretório da língua será usado por padrão. Tags de línguas com subtags regionais (e.x. "pt-BR"
ou "en-US"
) irão utilizar as traduções de UI integradas de sua língua base se nenhuma tradução específica da região for encontrada.
dir
tipo: 'ltr' | 'rtl'
A direção de escrita dessa língua; "ltr"
para esquerda-para-direita (o padrão) ou "rtl"
para direita-para-esquerda.
Local raiz
Você pode definir a língua padrão sem um diretório /lingua/
definindo um local root
:
Por exemplo, isso te permite servir /getting-started/
como uma rota em Inglês e utiliazr /fr/getting-started/
como a página equivalente em Francês.
defaultLocale
tipo: string
Define a língua que é padrão para esse site.
O valor deve corresponder uma das chaves do seu objeto locales
.
(Se sua língua padrão é seu local raiz, você pode pular isso.)
O local padrãoserá utilizado para providenciar conteúdo de fallback onde está se faltando traduções.
social
tipo: Partial<Record<'bitbucket' | 'codeberg' | 'codePen' | 'discord' | 'email' | 'facebook' | 'github' | 'gitlab' | 'gitter' | 'instagram' | 'linkedin' | 'mastodon' | 'matrix' | 'microsoftTeams' | 'openCollective' | 'patreon' | 'reddit' | 'rss' | 'signal' | 'slack' | 'stackOverflow' | 'telegram' | 'threads' | 'twitch' | 'twitter' | 'x.com' | 'youtube', string>>
Detalhes opcionais sobre as contas de redes sociais para esse site. Adicionar qualquer um desses irá os mostrar como links de ícone no cabeçalho do site.
customCss
tipo: string[]
Fornece arquivos CSS para customizar a aparência e sensação do seu site Starlight.
Suporta arquivos CSS locais relativos a raiz do seu projeto, e.x. './src/customizado.css'
e CSS que você instalou como um módulo do npm, e.x. '@fontsource/roboto'
.
expressiveCode
tipo: StarlightExpressiveCodeOptions | boolean
padrão:: true
Starlight usa Expressive Code
para renderizar blocos de código e adicionar suporte para destacar partes de códigos de exemplo, adicionar nomes de arquivos aos blocos de código, e mais.
Veja o guia para “Blocos de Código” para aprender como usar a sintaxe do Expressive Code dentro de seu conteúdo Markdown e MDX.
Você pode utilizar qualquer uma das opções de configuração do Expressive Code padrões, assim como alguma propriedades específicas do Starlight, configurando a opção expressiveCode
do Starlight.
Por exemplo, defina um valor para styleOverrides
do Expressive Code para sobrescrever o CSS padrão. Isso permite customizações como adicionar cantos arredondados aos seus blocos de código:
Se você quiser desabilitar o Expressive Code, define expressiveCode: false
em sua configuração do Starlight:
Além das opções padrões do Expressive Code, você também pode definir as seguintes propriedades específicas do Starlight na sua configuração expressiveCode
para customizar o comportamento de tema dos seus blocos de código:
themes
tipo: Array<string | ThemeObject | ExpressiveCodeTheme>
padrão: ['starlight-dark', 'starlight-light']
Define os temas utilizados para estilizar blocos de código.
Veja a documentação do Expressive Code sobre themes
para saber os formatos de temas suportados.
Starlight usa as variantes “light” e “dark” do tema Night Owl de Sarah Drasner por padrão.
Se você prover ao menos um tema claro e um escuro, Starlight vai automaticamente manter o tema de blocos de código ativo em sincronia com o tema atual do site.
Configure este comportamento com a opção useStarlightDarkModeSwitch
.
useStarlightDarkModeSwitch
tipo: boolean
padrão: true
Quando true
, blocos de código alternam automaticamente entre temas claro e escuro quando o tema do site muda.
Quando false
, você deve adicionar manualmente o CSSS para trocar entre os múltiplos temas.
useStarlightUiThemeColors
tipo: boolean
padrão: true
se themes
não for definido, caso contrário false
Quando true
, as variáveis de CSS do Starlight são utilizadas para as cores dos elementos de UI dos blocos de código (fundo, botões, sombras, etc.), correspondendo ao tema de cores do site.
Quando false
, as cores provenientes do tema de highlight de sintaxe ativo são utilizadas para estes elementos.
pagefind
tipo: boolean
padrão: true
Define se o Pagefind, provedor de busca dentro do site padrão do Starlight, está habilitado.
Defina como false
para desabilitar a indexação de seu site com Pagefind.
Isso também vai ocultar a UI de busca padrão se utilizado.
head
tipo: HeadConfig[]
Adiciona tags customizadas ao <head>
do seu site Starlight.
Pode ser útil para adicionar rastreamento de analytics e outros scripts e recursos de terceiros.
HeadConfig
lastUpdated
tipo: boolean
padrão: false
Controla se o rodapé mostra quando a página foi atualizada pela última vez.
Por padrão, essa funcionalidade depende no histórico do Git do seu repositório e pode não ser preciso em algumas plataformas de deployment utilizando shallow clones. Uma página pode sobrescrever essa opção ou a data baseada no Git utilizando o campo frontmatter lastUpdated
.
pagination
tipo: boolean
padrão: true
Define se o rodapé deve incluir links para a próxima página e a anterior.
Uma página pode sobrescrever essa opção ou o texto do link e/ou a URL usando os campos do frontmatter prev
e next
.
favicon
tipo: string
padrão: '/favicon.svg'
Define o caminho do favicon padrão para seu website que deve estar localizado no diretório public/
e ser um arquivo de ícone válido (.ico
, .gif
, .jpg
, .png
ou .svg
).
Se você precisa definir variantes adicionais ou favicons de fallback, você pode adicionar tags utilizando a opção head
:
titleDelimiter
tipo: string
padrão: '|'
Define o delimitador entre o título da página e o título do site na tag <title>
, o qual é exibido na aba do navegador.
Por padrão toda página tem o <title>
no formato Título da Página | Título do Site
.
Por exemplo, o título da página atual é “Referência da Configuração” e o título do site “Starlight”, então o <title>
é “Referência da Configuração | Starlight”.
components
tipo: Record<string, string>
Fornece os caminhos para os componentes que substituirão os componentes padrões do Starlight.
Consulte a Referencia de Substituição para ver os detalhes de todos os componentes que você pode substituir.
plugins
tipo: StarlightPlugin[]
Estenda Starlight com plugins customizados. Plugins aplicam mudanças em seu projeto para modificar ou adicionar funcionalidades ao Starlight.
Visite o mostruário de plugins para ver a lista de plugins disponíveis.
Veja a Referência de plugins para mais detalhes sobre como criar seus próprios plugins.