Astro Docs

Este gerador cria um site de documentação alimentado por Astro e o tema de documentação Starlight. Ele configura localização, snippets de conteúdo reutilizáveis, links internos com reconhecimento de localidade e um plugin starlight-blog por padrão.

Por padrão, ele também cria um pipeline de tradução automatizado alimentado por um Strands Agent no Amazon Bedrock.

Uso

Gerar um site de documentação Astro

Você pode gerar um novo site de documentação Astro de duas maneiras:

CLI
VSCode

pnpm nx g @aws/nx-plugin:ts#docs

yarn nx g @aws/nx-plugin:ts#docs

npx nx g @aws/nx-plugin:ts#docs

bunx nx g @aws/nx-plugin:ts#docs

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm nx g @aws/nx-plugin:ts#docs --dry-run

yarn nx g @aws/nx-plugin:ts#docs --dry-run

npx nx g @aws/nx-plugin:ts#docs --dry-run

bunx nx g @aws/nx-plugin:ts#docs --dry-run

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - ts#docs
Preencha os parâmetros obrigatórios
Clique em Generate

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	docs	O nome do projeto de documentação.
directory	string	.	O diretório pai onde o projeto de documentação é colocado.
subDirectory	string	-	O subdiretório onde o projeto de documentação é colocado. O padrão é o nome do projeto em kebab-case.
framework	astro	astro	O framework de documentação a ser usado.
noTranslation	boolean		Desativar o pipeline automatizado de tradução de documentação (Strands Agent no Amazon Bedrock + um target de projeto `translate`).
noBlog	boolean		Desativar o plugin `starlight-blog` e o post de blog de exemplo.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

Por padrão, o gerador cria a seguinte estrutura de projeto em docs/ na raiz do workspace (configurável através das opções name, directory e subDirectory):

astro.config.mjs Astro + Starlight configuration (locales, sidebar, blog plugin)
tsconfig.json Extends astro/tsconfigs/strict with @components / @assets path aliases
project.json Nx project with build, start, preview (and translate if enabled) targets
Directoryscripts
- translate.ts Translation driver — a Strands agent with a scoped file-editor tool (omitted with --noTranslation)
- translate.config.json Source/target locales, glob patterns, model id, region (omitted with --noTranslation)
Directorysrc
- Directorycomponents
  - link.astro Locale-aware link component (resolves paths against the current locale)
  - snippet.astro Locale-aware snippet loader component
- Directorycontent
  - Directorydocs
    Directoryen
    index.mdx Landing page
    Directoryguides
    getting-started.mdx Sample guide referencing the link and snippet components
    Directoryblog
    welcome.mdx Sample blog post (omitted with --noBlog)
    Directorysnippets
    example.mdx Sample reusable snippet
- Directorystyles
  - custom.css Starlight theme overrides
README.md Project README

Localização

O gerador usa como padrão uma única localidade (en) e redireciona a URL raiz para ela. Para adicionar mais idiomas:

Adicione uma entrada em locales no astro.config.mjs (por exemplo ko: { label: '한국어' }).
Crie um diretório correspondente em src/content/docs/<locale>/.
Preencha-o manualmente ou use o target de tradução descrito abaixo.

Tradução

A menos que você tenha passado --noTranslation, o gerador adiciona um target translate ao project.json, então você pode executar:

pnpm nx translate docs -- --all
pnpm nx translate docs -- --languages jp,ko
pnpm nx translate docs -- --dry-run

yarn nx translate docs -- --all
yarn nx translate docs -- --languages jp,ko
yarn nx translate docs -- --dry-run

npx nx translate docs -- --all
npx nx translate docs -- --languages jp,ko
npx nx translate docs -- --dry-run

bunx nx translate docs -- --all
bunx nx translate docs -- --languages jp,ko
bunx nx translate docs -- --dry-run

Quando executado sem --all, o script traduz apenas os arquivos que foram alterados desde o último commit de tradução no branch atual — o que significa que você pode executá-lo novamente com segurança em cada PR de documentação sem retraduzir todo o site.

Traduções cujo arquivo de origem não existe mais são excluídas, então renomear ou remover uma página não deixa cópias obsoletas em cada localidade.

Cada tradução é escrita como um arquivo completo. O agente recebe o código-fonte, a tradução existente e um diff do que mudou, e reutiliza a redação existente para seções que o diff deixou intactas — então apenas a prosa que o diff tocou é retraduzida, e blocos de código são copiados do código-fonte como estão.

Configurando a tradução

Edite scripts/translate.config.json para alterar:

Campo	Propósito
`sourceLanguage`	Localidade para traduzir de (padrão `en`).
`targetLanguages`	Localidades para traduzir para. Vazio por padrão. Por exemplo `["fr", "de", "es", "ja", "ko"]`.
`docsDir`	Caminho para o diretório de conteúdo de documentação, relativo à raiz do projeto.
`include`	Padrões glob (relativos a `<docsDir>/<sourceLanguage>`) para arquivos a traduzir.
`exclude`	Padrões glob a ignorar.
`modelId`	Modelo Bedrock a usar para traduções.
`awsRegion`	Região AWS com a qual o cliente Bedrock está configurado. Também pode ser definido via `AWS_REGION`.
`concurrency`	Número máximo de invocações simultâneas do agente.
`translationCommitMessage`	Marcador de mensagem de commit para commits de tradução (padrão `docs: update translations`).

Links internos com reconhecimento de localidade

O gerador fornece um componente Link que resolve automaticamente caminhos internos de documentação em relação à localidade atual, então uma única fonte de verdade produz a URL correta em todos os idiomas:

import Link from '@components/link.astro';

<Link path="guides/getting-started">Read the getting-started guide</Link>

Snippets

Fragmentos de conteúdo reutilizáveis ficam em src/content/docs/<locale>/snippets/. O componente Snippet gerado carrega o snippet que corresponde à localidade atual:

import Snippet from '@components/snippet.astro';

<Snippet name="example" />

Configurando CI

Nenhum workflow de CI é gerado por padrão — adicione um que:

Configure credenciais AWS com permissão para invocar Bedrock InvokeModel no modelo configurado.
Execute o target translate em pull requests que tocam sua documentação no idioma de origem:
- pnpm
- yarn
- npm
- bun
Terminal window
pnpm nx translate docs
Terminal window
yarn nx translate docs
Terminal window
npx nx translate docs
Terminal window
bunx nx translate docs
Faça commit das traduções resultantes de volta ao branch do PR. A mensagem de commit deve corresponder ao valor translationCommitMessage em scripts/translate.config.json (padrão docs: update translations) para que execuções incrementais subsequentes possam detectar o commit de linha de base e apenas retraduzir os arquivos que mudaram desde então.