Veja isso
Conteúdo interessante que você quer destacar.
Componentes
Componentes te permitem facilmente reutilizar pedaços da UI ou estilizar consistentemente. Alguns exemplos são um cartão de link ou um embed do YouTube. Starlight suporta o uso de componentes em arquivos MDX e providencia alguns components comuns para você utilizar.
Aprenda mais sobre como construir componentes na documentação do Astro.
Utilizando um componente
Você pode utilizar um componente ao importá-lo em seu arquivo MDX e então renderizá-lo como uma tag JSX.
Elas se parecem com tags HTML porém começam com uma letra maiúscula correspondente ao nome na sua declaração import:
---title: Bem-vindo a minha documentação---
import AlgumComponente from '../../components/AlgumComponente.astro';import OutroComponente from '../../components/OutroComponente.astro';
<AlgumComponente prop="algo" />
<OutroComponente> Componentes também podem conter **conteúdo aninhado**.</OutroComponente>Já que Starlight é feito com Astro, você pode adicionar suporte para componentes feitos com qualquer framework de UI suportado (React, Preact, Svelte, Vue, Solid, Lit e Alpine) em seus arquivos MDX. Aprenda mais sobre como utilizar componentes no MDX na documentação do Astro.
Compatibilidade com os estilos do Starlight
Starlight aplica estilos padrões para seu conteúdo Markdown, como por exemplo, adicionando margem entre elementos.
Se esses estilos conflitam com a aparência do seu componente, defina a classe not-content no seu componente para desabilitá-los.
<div class="not-content"> <p>Não é impactado pelos estilos padrões de conteúdo do Starlight.</p></div>Componentes integrados
Starlight providencia alguns componentes integrados para casos de uso comuns em documentações.
Esses componentes estão disponíveis através do pacote @astrojs/starlight/components.
Abas
Você pode mostrar uma interface com abas utilizando os componentes <Tabs> e <TabItem>.
Cada <TabItem> tem que ter uma label para mostrar aos usuários.
Use o atributo opcional icon para incluir um dos ícones predefinidos do Starlight ao lado da label.
import { Tabs, TabItem } from '@astrojs/starlight/components';
<Tabs> <TabItem label="Estrelas" icon="star"> Sirius, Vega, Betelgeuse </TabItem> <TabItem label="Luas" icon="moon"> Io, Europa, Ganimedes </TabItem></Tabs>O código acima gera as seguintes abas na página:
Sirius, Vega, Betelgeuse
Io, Europa, Ganimedes
Abas sincronizadas
Mantenha vários grupos de abas sincronizados adicionando o atributo syncKey.
Todas as <Tabs> em uma página com o mesmo valor syncKey exibirão a mesma label ativa. Isso permite que o leitor escolha uma vez (por exemplo, o sistema operacional ou o gerenciador de pacotes) e veja essa escolha refletida em toda a página.
Para sincronizar as abas relacionadas, adicione uma propriedade syncKey idêntica a cada componente <Tabs> e certifique-se de que todos eles usem as mesmas labels de <TabItem>:
import { Tabs, TabItem } from '@astrojs/starlight/components';
_Algumas estrelas:_
<Tabs syncKey="constelações"> <TabItem label="Orion">Bellatrix, Rígel, Betelgeuse</TabItem> <TabItem label="Gemini">Pólux, Castor A, Castor B</TabItem></Tabs>
_Alguns exoplanetas:_
<Tabs syncKey="constelações"> <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> <TabItem label="Gemini">Pólux b, HAT-P-24b, HD 50554 b</TabItem></Tabs>O código acima gera o seguinte na página:
Algumas estrelas:
Alguns exoplanetas:
Cartões
Você pode mostrar conteúdo em uma caixa seguindo os estilos do Starlight utilizando o componente <Card>.
Coloque múltiplos cartões no componente <CardGrid> para mostrar cartões lado a lado quando houver espaço suficiente.
Um <Card> precisa de um title e pode opcionalmente incluir o atributo icon para definir o nome de um dos ícones integrados do Starlight.
import { Card, CardGrid } from '@astrojs/starlight/components';
<Card title="Veja isso">Conteúdo interessante que você quer destacar.</Card>
<CardGrid> <Card title="Estrelas" icon="star"> Sirius, Vega, Betelgeuse </Card> <Card title="Luas" icon="moon"> Io, Europa, Ganimedes </Card></CardGrid>O código acima gera o seguinte na página:
Estrelas
Sirius, Vega, Betelgeuse
Luas
Io, Europa, Ganimedes
Cartões de Link
Utilize o componente <LinkCard> para fazer um link proeminente para outras páginas.
Um <LinkCard> precisa de um title e um atributo href. Você pode opcionalmente incluir uma pequena description ou outros atributos de link como target.
Agrupe múltiplos componentes <LinkCard> em um <CardGrid> para mostrar cartões lado a lado quando houver espaço suficiente.
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
<LinkCard title="Customizando Starlight" description="Aprenda como fazer seu site Starlight único com estilos customizados, fontes e mais." href="/pt-br/guides/customization/"/>
<CardGrid> <LinkCard title="Escrevendo Markdown" href="/pt-br/guides/authoring-content/" /> <LinkCard title="Componentes" href="/pt-br/guides/components/" /></CardGrid>O código acima gera o seguinte na página:
Customizando Starlight Aprenda como fazer seu site Starlight único com estilos customizados, fontes e mais.
Asides
Asides (também conhecidos como “advertências” ou “frases de destaque”) são úteis para exibir informações secundárias ao lado do conteúdo principal de uma página.
Um <Aside> pode ter um type opcional de note (o padrão), tip, caution ou danger. A definição de um atributo title substitui o título padrão do aside.
import { Aside } from '@astrojs/starlight/components';
<Aside>Um aside padrão sem um título personalizado.</Aside>
<Aside type="caution" title="Cuidado!"> Um aside de aviso *com* um título personalizado.</Aside>
<Aside type="tip">
Outros conteúdos também são compatíveis com asides.
```js// Um trecho de código, por exemplo.```
</Aside>
<Aside type="danger">Não forneça sua senha a ninguém.</Aside>O código acima gera o seguinte na página:
O Starlight também fornece uma sintaxe personalizada para renderizar asides em Markdown e MDX como uma alternativa ao componente <Aside>.
Consulte o guia “Escrevendo Conteúdo em Markdown” para obter detalhes sobre a sintaxe personalizada.
Código
Use o componente <Code> para renderizar código com syntax highlighting quando não for possível usar um bloco de código Markdown, por exemplo, para renderizar dados provenientes de fontes externas, como arquivos, bancos de dados ou APIs.
Consulte a documentação do “Componente de código” do Expressive Code para obter detalhes completos sobre as propriedades suportadas pelo <Code>.
import { Code } from '@astrojs/starlight/components';
export const codigoExemplo = `console.log('Isso pode vir de um arquivo ou CMS!');`;export const nomeArquivo = 'exemplo.js';export const destaques = ['arquivo', 'CMS'];
<Code code={codigoExemplo} lang="js" title={nomeArquivo} mark={destaques} />O código acima gera o seguinte na página:
console.log('Isso pode vir de um arquivo ou CMS!');Código importado
Use o sufixo de importação ?raw do Vite para importar qualquer arquivo de código como uma string.
Em seguida, você pode passar essa string importada para o componente <Code> para incluí-la em sua página.
import { Code } from '@astrojs/starlight/components';import codigoImportado from '/src/env.d.ts?raw';
<Code code={codigoImportado} lang="ts" title="src/env.d.ts" />O código acima gera o seguinte na página:
/// <reference path="../.astro/types.d.ts" />/// <reference types="astro/client" />Árvore de arquivos
Use o componente <FileTree> para exibir a estrutura de um diretório com ícones de arquivos e subdiretórios colapsáveis.
Especifique a estrutura de seus arquivos e diretórios com uma lista Markdown não ordenada dentro de <FileTree>.
Crie um subdiretório usando uma lista aninhada ou adicione uma / ao final de um item da lista para renderizá-lo como um diretório sem conteúdo específico.
A sintaxe a seguir pode ser usada para personalizar a aparência da árvore de arquivos:
- Destaque um arquivo ou diretório tornando seu nome em negrito, por exemplo,
**README.md**. - Adicione um comentário a um arquivo ou diretório acrescentando mais texto após o nome.
- Adicione arquivos e diretórios placeholder usando
...ou…como nome.
import { FileTree } from '@astrojs/starlight/components';
<FileTree>
- astro.config.mjs um arquivo **importante**- package.json- README.md- src - components - **Header.astro** - …- pages/
</FileTree>O código acima gera o seguinte na página:
- astro.config.mjs um arquivo importante
- package.json
- README.md
Directorysrc
Directorycomponents
- Header.astro
- …
Directorypages/
- …
Etapas
Use o componente <Steps> para estilizar listas numeradas de tarefas.
Isso é útil para guias passo a passo mais complexos, em que cada etapa precisa ser claramente destacada.
Envolva uma lista ordenada padrão do Markdown com o <Steps>.
Toda a sintaxe usual do Markdown é aplicável dentro de <Steps>.
import { Steps } from '@astrojs/starlight/components';
<Steps>
1. Importe o componente em seu arquivo MDX:
```js import { Steps } from '@astrojs/starlight/components'; ```
2. Envolva seus itens de lista ordenada com `<Steps>`.
</Steps>O código acima gera o seguinte na página:
-
Importe o componente em seu arquivo MDX:
import { Steps } from '@astrojs/starlight/components'; -
Envolva seus itens de lista ordenada com
<Steps>.
Ícone
Starlight providencia um conjunto comum de ícones que você pode mostrar em seu conteúdo utilizando o componente <Icon>.
Cada <Icon> requer um name e pode opcionalmente incluir um atributo label, size e color.
import { Icon } from '@astrojs/starlight/components';
<Icon name="star" color="goldenrod" size="2rem" />O código acima gera o seguinte na página:
Todos os ícones
Uma lista de todos os ícones disponíveis é mostrada abaixo com seus nomes associados. Clique em um ícone para copiar o código do componente dele.