Referência de Substituição

Você pode substituir os componentes padrões do Starlight fornecendo o caminho do componente a ser substituido no campo components nas configurações do Starlight. Esta página lista todos os componentes disponíveis para substituição e links do GitHub para a implementação padrão.

Props de componentes

Todos os componentes podem acessar o objeto padrão Astro.props que contém informações sobre a página em que se encontra.

Para tipar seus componentes personalizados, importe o tipo Props do Starlight:

---
import type { Props } from '@astrojs/starlight/props';

const { hasSidebar } = Astro.props;
//      ^ tipo: boolean
---

Assim você terá autocomplete e tipos quando acessar Astro.props.

Props

O Starlight passará os seguintes props aos seus componentes personalizados.

`dir`

Tipos: 'ltr' | 'rtl'

Direção de escrita da página.

`lang`

Tipos: string

Etiqueta BCP-47 do local da página atual, ex: en, zh-CN, ou pt-BR.

`locale`

Tipos: string | undefined

O caminho base de onde o idioma é servido. undefined para slugs do locale raiz.

`slug`

Tipos: string

O slug da página atual, gerado a partir do nome do arquivo.

`id`

Tipos: string

ID único para a página, baseado no nome do arquivo.

`isFallback`

Tipos: true | undefined

Será true se a página não tiver tradução no idioma atual e estiver utilizando conteúdo de fallback do local raiz. Usado apenas em site multilíngues.

`entryMeta`

Tipos: { dir: 'ltr' | 'rtl'; lang: string }

Metadados do local do conteúdo da página. Pode ser diferente do local atual quando a página estiver utilizando conteúdo de fallback.

`entry`

A entrada da coleção de conteúdo do Astro para a página atual. Inclui valores do frontmatter para a página atual em entry.data.

entry: {
  data: {
    title: string;
    description: string | undefined;
    // etc.
  }
}

Leia mais sobre as propriedades desse objeto na referência de Coleção de Conteúdo Astro

`sidebar`

Tipos: SidebarEntry[]

Entradas de navegação da barra lateral na página.

`hasSidebar`

Tipos: boolean

Se a barra lateral será ou não exibida na página.

`pagination`

Tipos: { prev?: Link; next?: Link }

Links para a próxima página e a anterior na barra lateral, se ativado.

`toc`

Tipos: { minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined

Sumário da página, se ativado.

`headings`

Tipos: { depth: number; slug: string; text: string }[]

Arranjo de todos os títulos Markdown extraídos da página atual. Utilize toc em vez disso se você deseja construir um componente de sumário que respeita as configurações do Starlight.

`lastUpdated`

Tipos: Date | undefined

Objeto Date JavaScript que representa quando a página foi atualizada pela última vez, se ativado.

`editUrl`

Tipos: URL | undefined

Objeto URL para o endereço onde a página poderá ser editada, se ativado.

`labels`

Tipos: Record<string, string>

Um objeto contendo as strings da UI localizados para a página atual. Veja o guia “Traduza a UI do Starlight” para uma lista de todas as chaves disponíveis.

Componentes

Head

Estes componentes são renderizados dentro do <head> de cada página. Deve-se apenas incluir elementos permitidos dentro do <head>

`Head`

Componente padrão: Head.astro

Componente renderizado dentro do <head> de cada página. Contém tags importantes como <title>, e <meta charset="utf-8">.

Substitua esse componente em último caso. Se possível, dê preferência as opções head de configuração do Starlight.

`ThemeProvider`

Componente padrão: ThemeProvider.astro

Componente renderizado dentro do <head> que configura o suporte para o tema claro/escuro. A implementação padrão embute um script e um <template> utilizado pelo script em <ThemeSelect />.

Acessibilidade

`SkipLink`

Componente padrão: SkipLink.astro

Para acessibilidade, esse componente é renderizado como primeiro elemento do <body>, é um link para o conteúdo principal da página atual. A implementação padrão fica invisível até o usuário focar nela utilizando a tecla Tab no teclado.

Layout

Estes componentes são responsáveis por dispor os componentes do Starlight e gerenciar a visualização através dos breakpoints. Substituí-los gera uma complexidade significativa. Se possível, prefira substituir componentes mais específicos.

`PageFrame`

Componente padrão: PageFrame.astro

Componente de layout que amarra a maioria do conteúdo da página. A implementação padrão monta o layout header–sidebar–main. Nele há slots nomeados header e sidebar, além do slot padrão para o conteúdo principal. Também renderiza o <MobileMenuToggle /> para dar suporte ao abrir/fechar a barra lateral em viewports menores (mobile).

`MobileMenuToggle`

Componente padrão: MobileMenuToggle.astro

Componente renderizado dentro do <PageFrame>, responsável por abrir ou fechar a barra lateral em viewports menores (mobile).

`TwoColumnContent`

Componente padrão: TwoColumnContent.astro

Componente de layout que amarra a coluna central e a barra da direita (sumário). A implementação padrão alterna o layout entre uma coluna, em viewport estreitas; e duas colunas, em viewports maiores.

Estes componentes renderizam a barra de navegação superior do Starlight

`Header`

Componente padrão: Header.astro

O componente Header é exibido no início de cada página. A implementação padrão exibe <SiteTitle />, <Search />, <SocialIcons />, <ThemeSelect />, e <LanguageSelect />.

`SiteTitle`

Componente padrão: SiteTitle.astro

Componente renderizado no início do Header que exibe o título do site. A implementação padrão inclui a lógica para renderizar os logos definidos nas configurações do Starlight.

`Search`

Componente padrão: Search.astro

Componente utilizado para renderizar a interface de busca. A implementação padrão inclui o botão no cabeçalho e o código para exibir o modal de busca quando for clicado e carregar a interface do Pagefind.

Quando pagefind está desabilitado, o componente de busca padrão não será renderizado. No entanto, se você substituir Search, seu componente customizado sempre será renderizado mesmo que a opção pagefind em sua configuração seja false. Isso lhe permite adicionar UI para provedores de busca alternativos ao desabilitar o Pagefind.

`SocialIcons`

Componente padrão: SocialIcons.astro

Componente renderizado no cabeçalho da página, incluindo links das mídias sociais. A implementação padrão utiliza a opção social nas configurações do Starlight para renderizar os links e ícones.

`ThemeSelect`

Componente padrão: ThemeSelect.astro

Componente renderizado no cabeçalho da página que permite aos usuários selecionar o tema preferido.

`LanguageSelect`

Componente padrão: LanguageSelect.astro

Componente renderizado no cabeçalho da página que permite escolher o idioma.

A barra lateral do Starlight inclue a navegação principal do site. Em telas menores fica invisível, podendo ser exibido via botão de dropdown.

`Sidebar`

Componente padrão: Sidebar.astro

Componente que contém a navegação global, renderizado ao lado do conteúdo da página. A implementação padrão exibe a barra lateral em viewports largas o suficiente e escondido sob um menu dropdown em viewports estreitas (mobile). Também renderiza o <MobileMenuFooter /> que exibe itens adicionais dentro do menu mobile.

`MobileMenuFooter`

Componente padrão: MobileMenuFooter.astro

Componente renderizado no final do menu dropdown mobile. A implementação padrão renderiza <ThemeSelect /> e <LanguageSelect />.

A barra lateral do Starlight é responsável por exibir o sumário delineando os subtítulos da página atual. Em viewports estreitas, fica sob um menu dropdown fixo.

`PageSidebar`

Componente padrão: PageSidebar.astro

Componente renderizado ao lado do conteúdo da página principal para exibir o sumário. A implementação padrão renderiza <TableOfContents /> e <MobileTableOfContents />.

`TableOfContents`

Componente padrão: TableOfContents.astro

Componente que renderiza o sumário da página atual em viewports largas.

`MobileTableOfContents`

Componente padrão: MobileTableOfContents.astro

Componente que renderiza o sumário da página atual em viewports estreitas (mobile).

Conteúdo

Componentes renderizados na coluna central da página.

`Banner`

Componente padrão: Banner.astro

Componente banner renderizado no início de cada página. A implementação padrão utiliza o valor do frontmatter banner para decidir se renderiza o banner ou não.

`ContentPanel`

Componente padrão: ContentPanel.astro

Componente de layout que amarra as seções da coluna central.

`PageTitle`

Componente padrão: PageTitle.astro

Componente contendo o elemento <h1> da página atual.

Certifique-se de adicionar id="_top" ao elemento <h1> assim como implementação padrão.

`FallbackContentNotice`

Componente padrão: FallbackContentNotice.astro

Aviso exibido aos visitantes da página quando a tradução para o idioma atual não estiver disponível. Apenas utilizado em site multilíngue.

`Hero`

Componente padrão: Hero.astro

Componente renderizado no início da página quando hero tiver configurado no frontmatter. A implementação padrão exibe um título grande, tagline, links de chamada de ação, e opcionalmente, uma imagem junto.

`MarkdownContent`

Componente padrão: MarkdownContent.astro

Componente renderizado ao redor do conteúdo principal de cada página. A implementação padrão adiciona estilos para o conteúdo Markdown.

O estilo dos conteúdos Markdown também é disponibilizado em @astrojs/starlight/style/markdown.css e limitados ao o escopo da classe de CSS .sl-markdown-content.

Estes componentes são renderizados no final da coluna de conteúdo principal da página.

`Footer`

Componente padrão: Footer.astro

Componente do rodapé exibido no final de cada página. A implementação padrão exibe <LastUpdated />, <Pagination />, e <EditLink />.

`LastUpdated`

Componente padrão: LastUpdated.astro

Componente renderizado no rodapé da página que a data de última atualização.

`EditLink`

Componente padrão: EditLink.astro

Componente renderizado no rodapé da página que exibe o link de onde a página poderá ser editada.

`Pagination`

Componente padrão: Pagination.astro

Componente renderizado no rodapé da página que exibe setas de navegação entre a próxima página e a anterior.

Referência de Substituição

Props de componentes

Props

dir

lang

locale

slug

id

isFallback

entryMeta

entry

sidebar

hasSidebar

pagination

toc

headings

lastUpdated

editUrl

labels

Componentes

Head

Head

ThemeProvider

Acessibilidade

SkipLink

Layout

PageFrame

MobileMenuToggle

TwoColumnContent

Header

Header

SiteTitle

Search

SocialIcons

ThemeSelect

LanguageSelect

Global Sidebar

Sidebar

MobileMenuFooter

Page Sidebar

PageSidebar

TableOfContents

MobileTableOfContents

Conteúdo

Banner

ContentPanel

PageTitle

FallbackContentNotice

Hero

MarkdownContent

Footer

Footer

LastUpdated

EditLink

Pagination

`dir`

`lang`

`locale`

`slug`

`id`

`isFallback`

`entryMeta`

`entry`

`sidebar`

`hasSidebar`

`pagination`

`toc`

`headings`

`lastUpdated`

`editUrl`

`labels`

`Head`

`ThemeProvider`

`SkipLink`

`PageFrame`

`MobileMenuToggle`

`TwoColumnContent`

`Header`

`SiteTitle`

`Search`

`SocialIcons`

`ThemeSelect`

`LanguageSelect`

`Sidebar`

`MobileMenuFooter`

`PageSidebar`

`TableOfContents`

`MobileTableOfContents`

`Banner`

`ContentPanel`

`PageTitle`

`FallbackContentNotice`

`Hero`

`MarkdownContent`

`Footer`

`LastUpdated`

`EditLink`

`Pagination`