Instalação Manual

A forma mais rápida de criar um novo site Starlight é utilizando create astro como é mostrado no guia Introdução. Se você deseja adicionar Starlight a um projeto Astro existente, este guia irá te explicar como.

Instale Starlight

Para seguir este guia, você vai precisar de um projeto Astro existente.

Adicione a integração Starlight

Starlight é uma integração Astro. Adicione-o ao seu site executando o comando astro add no diretório raiz do seu projeto:

npm

npx astro add starlight

pnpm

pnpm astro add starlight

Yarn

yarn astro add starlight

Ele vai instalar as dependências necessárias e adicionar o Starlight no array integrations do seu arquivo de configuração do Astro.

Configure a integração

A integração Starlight é configurada no seu arquivo astro.config.mjs.

Adicione um title para começar:

astro.config.mjs

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Meu brilhante site de documentação',
    }),
  ],
});

Encontre todas as opções disponíveis na referência de configuração do Starlight.

Configure coleções de conteúdo

Starlight é construído com base nas coleções de conteúdo do Astro, que são configuradas no arquivo src/content/config.ts.

Crie ou atualize o arquivo de configuração de conteúdo, adicionando uma coleção docs que usa o esquema docsSchema do Starlight:

src/content/config.ts

import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
};

Adicione conteúdo

Starlight agora está configurado e chegou a hora de adicionar algum conteúdo!

Crie um diretório src/content/docs/ e comece por adicionar um arquivo index.md. Essa será a página inicial do seu site:

src/content/docs/index.md

---
title: Minha documentação
description: Aprenda mais sobre meu projeto nesse site de documentação construído com Starlight.
---

Bem-vindo ao meu projeto!

Starlight usa roteamento baseado em arquivos, o que significa que todo arquivo Markdown, MDX ou Markdoc em src/content/docs/ se tornará uma página no seu site. Metadados do frontmatter (os campos title e description no exemplo acima) podem mudar como cada página é mostrada. Veja todas as opções disponíveis na referência de frontmatter.

Dicas para sites existentes

Se você tem um projeto Astro existente, você pode utilizar Starlight para rapidamente adicionar uma seção de documentação ao seu site.

Use Starlight como um subcaminho

Para adicionar todas as páginas do Starlight em um subcaminho, coloque todo o conteúdo da sua documentação dentro de um subdiretório de src/content/docs/.

Por exemplo, se todas as páginas do Starlight devem começar com /guias/, adicione seu conteúdo no diretório src/content/docs/guias/:

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryguias/

        • guia.md
        • index.md
  • Directorypages/

    • …
• astro.config.mjs

No futuro, planejamos suportar esse caso de uso melhor para evitar a necessidade de um diretório aninhado adicional em src/content/docs/.

Use Starlight com SSR

Atualmente, Starlight não suporta deployments com SSR usando os adaptadores de servidor do Astro. Nós esperamos ser capazes de suportar isso em breve.