Astro Docs

Este gerador cria a estrutura de 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:

VSCode
CLI

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#astro-docs
Preencha os parâmetros obrigatórios
Clique em Generate

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

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

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

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

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

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

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

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

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

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.
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 a postagem de blog de exemplo.
skipInstall	boolean		Ignorar a instalação de dependências após a execução do gerador.

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 Configuração do Astro + Starlight (locales, sidebar, plugin de blog)
tsconfig.json Estende astro/tsconfigs/strict com aliases de caminho @components / @assets
project.json Projeto Nx com targets build, start, preview (e translate se habilitado)
Directoryscripts
- translate.ts Driver de tradução — um agente Strands com uma ferramenta de edição de arquivos com escopo (omitido com --noTranslation)
- translate.config.json Locales de origem/destino, padrões glob, id do modelo, região (omitido com --noTranslation)
Directorysrc
- Directorycomponents
  - link.astro Componente de link com reconhecimento de localidade (resolve caminhos em relação à localidade atual)
  - snippet.astro Componente carregador de snippet com reconhecimento de localidade
- Directorycontent
  - Directorydocs
    Directoryen
    index.mdx Página inicial
    Directoryguides
    getting-started.mdx Guia de exemplo referenciando os componentes link e snippet
    Directoryblog
    welcome.mdx Post de blog de exemplo (omitido com --noBlog)
    Directorysnippets
    example.mdx Snippet reutilizável de exemplo
- Directorystyles
  - custom.css Substituições do tema Starlight
README.md README do projeto

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, para que você possa 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.

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 da 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 de agente simultâneas.
`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, de modo que uma única fonte de verdade produz a URL correta em todos os idiomas:

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

<Link path="guides/getting-started">Leia o guia de introdução</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 InvokeModel do Bedrock 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.