Instalação Manual

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

Instalação do Starlight

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

Adicione a integração Starlight

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

npm

sh npx astro add starlight

pnpm

sh pnpm astro add starlight

Yarn

sh yarn astro add starlight

Este passo irá instalar as dependências necessárias e adicionar o Starlight ao array de integrations do seu arquivo de configuração do Astro.

Configure a integração

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

Para começar adicione um title:

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'O meu magnífico site de documentação',
    }),
  ],
});

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

Configure coleções de conteúdos

O Starlight é construído com base nas coleções de conteúdos 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 os esquemas docsLoader e docsSchema do Starlight:

src/content/config.ts

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

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

O Starlight tambem suporta a opção legacy.collections onde as coleções são tratadas utilizando a implementação anterior das coleções de conteúdo. Isto é útil se tiver um projeto Astro existente e não pode, de momento, efetuar alterações às coleções para utilizar um loader.

Adicione conteúdo

Agora que o Starlight está configurado é hora de adicionar algum conteúdo!

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

src/content/docs/index.md

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

Bem-vindo ao meu projeto!

O Starlight usa routing baseado em arquivos, o que significa que qualquer arquivo Markdown, MDX ou Markdoc em src/content/docs/ corresponderá a uma página no seu site. Os metadados do frontmatter (campos title e description no exemplo acima) podem mudar como cada página é apresentada. Veja todas as opções disponíveis na referência do frontmatter.

Dicas para sites existentes

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

Utilize o Starlight como um sub-caminho

Para adicionar todas as páginas do Starlight num sub-caminho, coloque todo o conteúdo da sua documentação dentro de um sub-diretório de src/content/docs/.

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

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryguias/

        • guia.md
        • index.md
  • Directorypages/

    • …
• astro.config.mjs

No futuro, planeamos melhorar o suporte deste caso de uso para evitar a necessidade de um diretório adicional dentro do src/content/docs/.

Usar o Starlight com SSR

Para habilitar o SSR siga o guia “Adaptadores de renderização a pedido” da documentação do Astro e adicione um adaptador ao seu projeto Starlight.

Atualmente as páginas de documentação geradas pelo Starlight são sempre pré-renderizadas independentemente do modo de geração do projeto. Para desabilitar a pré-renderização das suas páginas Starlight coloque a opção de config prerender a false.