Customizando Starlight

Starlight providencia uma estilização e funcionalidades sensíveis padrões, para que você inicie rapidamente sem nenhuma configuração necessária.

Quando você quiser começar a customizar a aparência e sensação do seu site Starlight, este guia tem tudo o que você precisa.

Adicione sua logo

Adicionar uma logo customizada ao cabeçalho do site é uma forma rápida de adicionar sua marca individual a um site Starlight.

Adicione o arquivo de imagem da sua logo para o diretório src/assets/:
- Directorysrc/
  - Directoryassets/
    minha-logo.svg
  - Directorycontent/
    …
- astro.config.mjs

Adicione o caminho para sua logo como a opção logo.src do Starlight em astro.config.mjs:

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

export default defineConfig({
	integrations: [
		starlight({
			title: 'Documentação com Minha Logo',
			logo: {
				src: './src/assets/minha-logo.svg',
			},
		}),
	],
});

Por padrão, a logo será mostrada ao lado do title do seu site. Se sua imagem da logo já inclui o título do site, você pode esconder o texto do título visualmente ao definir a opção replacesTitle. O texto do title ainda será incluido para leitores de tela para que o cabeçalho continue acessível.

starlight({
  title: 'Documentação com Minha Logo',
  logo: {
    src: './src/assets/minha-logo.svg',
    replacesTitle: true,
  },
}),

Variantes clara e escura da logo

Você pode mostrar diferentes versões da sua logo no modo claro e escuro.

Adicione um arquivo de imagem para cada variante em src/assets/:
- Directorysrc/
  - Directoryassets/
    logo-clara.svg
    logo-escura.svg
  - Directorycontent/
    …
- astro.config.mjs

Adicione o caminho para suas variantes da logo como as opções light e dark ao invés de src em astro.config.mjs:

starlight({
  title: 'Documentação com Minha Logo',
  logo: {
    light: './src/assets/logo-clara.svg',
    dark: './src/assets/logo-escura.svg',
  },
}),

Habilitar o sitemap

O Starlight possui suporte integrado para a geração de um sitemap. Habilite a geração do sitemap definindo sua URL como site em astro.config.mjs:

// astro.config.mjs

export default defineConfig({
	site: 'https://stargazers.club',
	integrations: [starlight({ title: 'Site com sitemap' })],
});

Layout da página

Por padrão, páginas do Starlight usam um layout com uma barra de navegação lateral global e um índice que mostra os cabeçalhos da página atual.

Você pode aplicar um layout de página maior sem barras laterais definindo template: splash no frontmatter de uma página. Isso funciona particularmente bem para páginas iniciais e você pode vê-lo em ação na página inicial deste site.

---
# src/content/docs/index.md

title: Minha Página Inicial
template: splash
---

Índice

Starlight mostra um índice para cada página para tornar mais fácil para leitores pularem ao cabeçalho no qual estão procurando. Você pode customizar - ou até desabilitar - o índice globalmente na integração Starlight ou página a página no frontmatter.

Por padrão, cabeçalhos <h2> e <h3> são inclusos no índice. Modifique quais níveis de cabeçalho incluir ao redor do site utilizando as opções minHeadingLevel e maxHeadingLevel na global tableOfContents. Sobrescreva esses padrões em uma página individual adicionando as propriedades correspondentes do frontmatter tableOfContents:

Frontmatter
Configuração global

---
# src/content/docs/exemplo.md
title: Página com apenas H2s no índice
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---

// astro.config.mjs

defineConfig({
	integrations: [
		starlight({
			title: '',
			tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
		}),
	],
});

Desabilite o índice completamente definindo a opção tableOfContents como false:

Frontmatter
Configuração global

---
# src/content/docs/exemplo.md
title: Página sem um índice
tableOfContents: false
---

// astro.config.mjs

defineConfig({
	integrations: [
		starlight({
			title: 'Documentação com um índice desabilitado globalmente',
			tableOfContents: false,
		}),
	],
});

Links de redes sociais

Starlight tem suporte integrado para adicionar links de suas contas de redes sociais ao cabeçalho do site através da opção social na integração Starlight.

Você pode encontrar uma lista completa de ícones suportados na Referência de Configuração. Nos avise no GitHub ou Discord se você precisa de suporte para outro serviço!

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

export default defineConfig({
	integrations: [
		starlight({
			title: 'Documentação com Links de Redes Sociais',
			social: {
				discord: 'https://astro.build/chat',
				github: 'https://github.com/withastro/starlight',
			},
		}),
	],
});

Links de Edição

Starlight pode mostrar um link de “Editar página” no rodapé de cada página. Isso faz fácil para um leitor encontrar o arquivo para editar para melhorar sua documentação. Particularmente para projetos open-source, isso pode ajudar a encorajar contribuições da sua comunidade.

Para habilitar links de edição, defina editLink.baseUrl para a URL usada para editar seu repositório na configuração da integração Starlight. O valor de editLink.baseUrl será anexado ao caminho para a página atual para formar o link de edição completo.

Padrões comuns incluem:

GitHub: https://github.com/USUARIO/REPOSITORIO/edit/BRANCH/
GitLab: https://gitlab.com/USUARIO/REPOSITORIO/-/edit/BRANCH/

Se o seu projeto Starlight não está na raiz do seu repositório, inclua o caminho ao projeto no fim da URL base.

Este exemplo mostra o link de edição configurado para a documentação do Starlight, que vive no subdiretório docs/ da branch main do repositório withastro/starlight no GitHub:

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

export default defineConfig({
	integrations: [
		starlight({
			title: 'Documentação com Links de Edição',
			editLink: {
				baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
			},
		}),
	],
});

Página 404 Customizada

Sites Starlight mostram uma página 404 simples por padrão. Você pode customizá-la adicionando um arquivo 404.md (ou 404.mdx) ao seu diretório src/content/docs/:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    404.md
    index.md
astro.config.mjs

Você pode utilizar todas as técnicas de customização e layout de página do Starlight em sua página 404. Por exemplo, a página 404 padrão utiliza o template splash e o componente hero no frontmatter:

---
title: '404'
template: splash
editUrl: false
hero:
  title: '404'
  tagline: Página não encontrada. Verifique a URL ou tenta utilizar a barra de pesquisa.
---

Fontes customizadas

Por padrão, Starlight utiliza fontes sans-serif disponíveis no dispositivo local do usuário para todo o texto. Isso garante que a documentação carrega rapidamente em uma fonte que é familiar para cada usuário, sem precisar de largura de banda para baixar grandes arquivos de fonte.

Se você deve adicionar uma fonte customizada ao seu site Starlight, você pode definir fontes para usar em arquivos CSS customizados ou com qualquer outra técnica de estilização do Astro.

Configure fontes

Se você já tem arquivos de fonte, siga o guia de configuração local. Para utilizar Google Fonts, siga o guia de configuração do Fontsource.

Configure arquivos de fonte locais

Adicione seus arquivos de fonte para o diretório src/fonts/ e crie um arquivo vazio font-face.css:
- Directorysrc/
  - Directorycontent/
    …
  - Directoryfonts/
    FonteCustomizada.woff2
    font-face.css
- astro.config.mjs

Adicione uma declaração @font-face para cada uma de suas fontes em src/fonts/font-face.css. Utilize um caminho relativo para o arquivo de fonte na função url().

/* src/fonts/font-face.css */

@font-face {
	font-family: 'Fonte Customizada';
	/* Use um caminho relativo para o arquivo de fonte local em `url()`. */
	src: url('./FonteCustomizada.woff2') format('woff2');
	font-weight: normal;
	font-style: normal;
	font-display: swap;
}

Adicione o caminho para seu arquivo font-face.css ao array customCss do Starlight em astro.config.mjs:

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

export default defineConfig({
	integrations: [
		starlight({
			title: 'Documentação Com Meu Tipo de Letra Customizado',
			customCss: [
				// Caminho relativo para seu arquivo CSS @font-face.
				'./src/fonts/font-face.css',
			],
		}),
	],
});

Configure uma fonte do Fontsource

O projeto Fontsource simplifica a utilização de Google Fonts e outras fontes open-source. Ele providencia módulos do npm que você pode isntalar para as fontes que você quer usar e inclui arquivos CSS prontos para adicionar ao seu projeto.

Encontre a fonte que você quer utilizar no catálogo do Fontsource. Este exemplo irá utilizar IBM Plex Serif.
Instale o pacote da sua fonte escolhida. Você pode encontrar o nome do pacote clicando em “Install” na página de fontes do Fontsource.
- npm
- pnpm
- Yarn
```
npm install @fontsource/ibm-plex-serif
```
```
pnpm install @fontsource/ibm-plex-serif
```
```
yarn add @fontsource/ibm-plex-serif
```

Adicione os arquivos CSS do Fontsource ao array customCss do Starlight em astro.config.mjs:

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

export default defineConfig({
	integrations: [
		starlight({
			title: 'Documentação Com Meu Tipo de Letra Customizado',
			customCss: [
				// Arquivos do Fontsource para as espessuras de fonte regular e semi-negrito.
				'@fontsource/ibm-plex-serif/400.css',
				'@fontsource/ibm-plex-serif/600.css',
			],
		}),
	],
});

Fontsource envia múltiplos arquivos CSS para cada fonte. Veja a documentação do Fontsource em como incluir diferentes espessuras e estilos para entender quais utilizar.

Utilize fontes

Para aplicar a fonte que você definiu para o seu site, utilize o nome da sua fonte escolhida em um arquivo CSS customizado. Por exemplo, para sobrescrever a fonte padrão do Starlight em todo lugar, defina a propriedade customizada --sl-font:

/* src/styles/customizada.css */

:root {
	--sl-font: 'IBM Plex Serif', serif;
}

Você também pode escrever CSS mais específico se você quiser aplicar sua fonte mais seletivamente. Por exemplo, para definir uma fonte no conteúdo principal apenas, mas não nas barras laterais:

/* src/styles/customizada.css */

main {
	font-family: 'IBM Plex Serif', serif;
}

Siga as instruções de CSS customizado para adicionar seus estilos ao seu site.