Páginas

Starlight gera as páginas HTML do seu site com base no seu conteúdo, com opções flexíveis fornecidas através do frontmatter do Markdown. Além disso, os projetos Starlight têm acesso total às poderosas ferramentas de geração de páginas do Astro. Este guia mostra como a geração de páginas funciona no Starlight.

Páginas de conteúdo

Formatos de arquivo

Starlight suporta a autoria de conteúdo em Markdown e MDX sem necessidade de configuração. Você pode adicionar suporte para Markdoc instalando a integração experimental Astro Markdoc.

Adicionando páginas

Adicione novas páginas ao seu site criando arquivos .md ou .mdx em src/content/docs/. Utilize subpastas para organizar seus arquivos e criar múltiplos segmentos de caminho.

Por exemplo, a seguinte estrutura de arquivos irá gerar páginas em exemplo.com/ola-mundo e example.com/reference/faq:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    ola-mundo.md
    Directoryreference/
    faq.md

Frontmatter com segurança de tipos

Todas as páginas do Starlight compartilham um conjunto comum de propriedades de frontmatter personalizáveis para controlar como a página aparece:

---
title: Olá, Mundo!
description: Esta é uma página no meu site alimentado pelo Starlight
---

Se você esquecer de algo importante, o Starlight irá te avisar.

Páginas customizadas

Para casos de uso avançados, você pode adicionar páginas customizadas criando um diretório src/pages/. O diretório src/pages/ usa roteamento baseado em arquivos do Astro e inclui suporte para arquivos .astro entre outros formatos de página. Isto é útil se você precisa construir páginas com um layout completamente customizado ou gerar uma página a partir de uma fonte de dados alternativa.

Por exemplo, este projeto mistura conteúdo Markdown em src/content/docs/ com rotas Astro e HTML em src/pages/:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    ola-mundo.md
- Directorypages/
  - custom.astro
  - archived.html

Usando o design do Starlight em páginas customizadas

Para usar o layout do Starlight em páginas customizadas, envolva o conteúdo da sua página com o componente <StarlightPage />. Isto pode ser útil se você estiver gerando conteúdo dinamicamente mas ainda quiser usar o design do Starlight.

---
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
import CustomComponent from './CustomComponent.astro';
---

<StarlightPage frontmatter={{ title: 'Minha página customizada' }}>
  <p>Esta é uma página customizada com um componente customizado:</p>
  <CustomComponent />
</StarlightPage>

Props

O componente <StarlightPage /> aceita as seguintes props.

`frontmatter` (obrigatório)

tipo: StarlightPageFrontmatter

Especifique as propriedades de frontmatter para esta página, similar ao frontmatter em páginas Markdown. O title é requerido e todas as outras propriedades são opcionais.

As seguintes propriedades diferem do frontmatter Markdown:

O slug não é suportado e é automaticamente definido com base na URL da página customizada.
A opção editUrl requer uma URL para exibir um link de edição.
A propriedade sidebar para customizar como a página aparece em grupos de links autogerados não está disponível. Páginas usando o componente <StarlightPage /> não fazem parte de uma coleção e não podem ser adicionadas a um grupo de sidebar autogerado.

`sidebar`

tipo: SidebarEntry[]
ão: a barra lateral gerada baseado na configuração global sidebar

Provê uma barra lateral de navegação customizada para esta página. Caso não seja definido, a página usará a barra lateral global padrão.

Por exemplo, a seguinte página sobrescreve o sidebar padrão com um link para a página inicial e um grupo de links para diferentes constelações. A página atual na barra lateral é definida usando a propriedade isCurrent e um badge opcional foi adicionado a um item de link.

<StarlightPage
  frontmatter={{ title: 'Orion' }}
  sidebar={[
    { label: 'Início', href: '/' },
    {
      label: 'Constelações',
      items: [
        { label: 'Andromeda', href: '/andromeda/' },
        { label: 'Orion', href: '/orion/', isCurrent: true },
        { label: 'Ursa Minor', href: '/ursa-minor/', badge: 'Stub' },
      ],
    },
  ]}
>
  Conteúdo de exemplo.
</StarlightPage>

`hasSidebar`

tipo: boolean
padrão: false se frontmatter.template é 'splash', caso contrário é true

Controle se a barra lateral deve ser exibida nesta página.

`headings`

tipo: { depth: number; slug: string; text: string }[]
padrão: []

Provê um array com todos os títulos na página. Starlight irá gerar o sumário da página a partir destes títulos se fornecidos.

`dir`

tipo: 'ltr' | 'rtl'
padrão: a direção de escrita para a localidade atual

Define a direção de escrita para o conteúdo da página.

`lang`

tipo: string
padrão: a linguagem da localidade atual

Define a tag de linguagem BCP-47 para o conteúdo da página, por exemplo, en, zh-CN, ou pt-BR.

`isFallback`

tipo: boolean
padrão: false

Indica se esta página está usando conteúdo fallback porque não há tradução para a linguagem atual.