Astro Docs

Questo generatore crea l’impalcatura di un sito di documentazione basato su Astro e il tema di documentazione Starlight. Configura la localizzazione, frammenti di contenuto riutilizzabili, link interni consapevoli della lingua e un plugin starlight-blog per impostazione predefinita.

Per impostazione predefinita, crea anche una pipeline di traduzione automatizzata basata su uno Strands Agent su Amazon Bedrock.

Utilizzo

Generare un sito di documentazione Astro

Puoi generare un nuovo sito di documentazione Astro in due modi:

VSCode
CLI

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - ts#astro-docs
Compila i parametri richiesti
Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	docs	Il nome del progetto di documentazione.
directory	string	.	La directory padre in cui viene posizionato il progetto di documentazione.
subDirectory	string	-	La sotto-directory in cui viene posizionato il progetto di documentazione. Il valore predefinito è il nome del progetto in formato kebab-case.
noTranslation	boolean		Escludere la pipeline di traduzione automatica della documentazione (Strands Agent su Amazon Bedrock + un target di progetto `translate`).
noBlog	boolean		Escludere il plugin `starlight-blog` e il post del blog di esempio.
skipInstall	boolean		Salta l'installazione delle dipendenze dopo l'esecuzione del generatore.

Output del generatore

Per impostazione predefinita, il generatore crea la seguente struttura di progetto in docs/ nella radice del workspace (configurabile tramite le opzioni name, directory e subDirectory):

astro.config.mjs Configurazione Astro + Starlight (locali, sidebar, plugin blog)
tsconfig.json Estende astro/tsconfigs/strict con alias di percorso @components / @assets
project.json Progetto Nx con target build, start, preview (e translate se abilitato)
Directoryscripts
- translate.ts Driver di traduzione — uno Strands agent con uno strumento file-editor con ambito (omesso con --noTranslation)
- translate.config.json Locali sorgente/destinazione, pattern glob, id modello, regione (omesso con --noTranslation)
Directorysrc
- Directorycomponents
  - link.astro Componente link consapevole della lingua (risolve i percorsi rispetto alla lingua corrente)
  - snippet.astro Componente caricatore di snippet consapevole della lingua
- Directorycontent
  - Directorydocs
    Directoryen
    index.mdx Pagina di destinazione
    Directoryguides
    getting-started.mdx Guida di esempio che fa riferimento ai componenti link e snippet
    Directoryblog
    welcome.mdx Post del blog di esempio (omesso con --noBlog)
    Directorysnippets
    example.mdx Snippet riutilizzabile di esempio
- Directorystyles
  - custom.css Override del tema Starlight
README.md README del progetto

Localizzazione

Il generatore utilizza per impostazione predefinita una singola lingua (en) e reindirizza l’URL radice ad essa. Per aggiungere altre lingue:

Aggiungi una voce sotto locales in astro.config.mjs (ad esempio ko: { label: '한국어' }).
Crea una directory corrispondente sotto src/content/docs/<locale>/.
Popolala manualmente o utilizza il target di traduzione descritto di seguito.

Traduzione

A meno che tu non abbia passato --noTranslation, il generatore aggiunge un target translate a project.json, quindi puoi eseguire:

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 eseguito senza --all, lo script traduce solo i file che sono cambiati dall’ultimo commit di traduzione sul branch corrente — il che significa che puoi rieseguirlo in sicurezza su ogni PR di documentazione senza ritradurre l’intero sito.

Configurazione della traduzione

Modifica scripts/translate.config.json per cambiare:

Campo	Scopo
`sourceLanguage`	Lingua da cui tradurre (predefinito `en`).
`targetLanguages`	Lingue verso cui tradurre. Vuoto per impostazione predefinita. Ad esempio `["fr", "de", "es", "ja", "ko"]`.
`docsDir`	Percorso della directory del contenuto della documentazione, relativo alla radice del progetto.
`include`	Pattern glob (relativi a `<docsDir>/<sourceLanguage>`) per i file da tradurre.
`exclude`	Pattern glob da saltare.
`modelId`	Modello Bedrock da utilizzare per le traduzioni.
`awsRegion`	Regione AWS con cui è configurato il client Bedrock. Può anche essere impostato tramite `AWS_REGION`.
`concurrency`	Numero massimo di invocazioni simultanee dell’agent.
`translationCommitMessage`	Marcatore del messaggio di commit per i commit di traduzione (predefinito `docs: update translations`).

Link interni consapevoli della lingua

Il generatore fornisce un componente Link che risolve automaticamente i percorsi interni della documentazione rispetto alla lingua corrente, in modo che un’unica fonte di verità produca l’URL corretto in ogni lingua:

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

<Link path="guides/getting-started">Leggi la guida introduttiva</Link>

Snippet

I frammenti di contenuto riutilizzabili si trovano in src/content/docs/<locale>/snippets/. Il componente Snippet generato carica lo snippet che corrisponde alla lingua corrente:

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

<Snippet name="example" />

Configurazione della CI

Nessun workflow CI viene generato di default — aggiungine uno che:

Configura le credenziali AWS con il permesso di invocare InvokeModel di Bedrock sul modello configurato.
Esegue il target translate sulle pull request che toccano la documentazione nella lingua sorgente:
- 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
Esegue il commit delle traduzioni risultanti nel branch della PR. Il messaggio di commit deve corrispondere al valore translationCommitMessage in scripts/translate.config.json (predefinito docs: update translations) in modo che le successive esecuzioni incrementali possano rilevare il commit di base e ritradurre solo i file che sono cambiati da allora.