Astro Docs

Este generador crea un sitio de documentación impulsado por Astro y el tema de documentación Starlight. Configura localización, fragmentos de contenido reutilizables, enlaces internos conscientes de la configuración regional y un plugin starlight-blog por defecto.

Por defecto también crea un pipeline de traducción automatizado impulsado por un Strands Agent en Amazon Bedrock.

Uso

Generar un sitio de documentación Astro

Puedes generar un nuevo sitio de documentación Astro de dos maneras:

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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 el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - ts#docs
Complete los parámetros requeridos
Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	docs	El nombre del proyecto de documentación.
directory	string	.	El directorio padre donde se coloca el proyecto de documentación.
subDirectory	string	-	El subdirectorio donde se coloca el proyecto de documentación. Por defecto es el nombre del proyecto en formato kebab-case.
framework	astro	astro	El framework de documentación a utilizar.
noTranslation	boolean		Excluirse del pipeline automatizado de traducción de documentación (Strands Agent en Amazon Bedrock + un target de proyecto `translate`).
noBlog	boolean		Excluirse del plugin `starlight-blog` y de la entrada de blog de ejemplo.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

Por defecto, el generador crea la siguiente estructura de proyecto en docs/ en la raíz del workspace (configurable a través de las opciones name, directory y 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
Directorioscripts
- 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)
Directoriosrc
- Directoriocomponents
  - link.astro Locale-aware link component (resolves paths against the current locale)
  - snippet.astro Locale-aware snippet loader component
- Directoriocontent
  - Directoriodocs
    Directorioen
    index.mdx Landing page
    Directorioguides
    getting-started.mdx Sample guide referencing the link and snippet components
    Directorioblog
    welcome.mdx Sample blog post (omitted with --noBlog)
    Directoriosnippets
    example.mdx Sample reusable snippet
- Directoriostyles
  - custom.css Starlight theme overrides
README.md Project README

Localización

El generador por defecto usa una sola configuración regional (en) y redirige la URL raíz a ella. Para agregar más idiomas:

Agrega una entrada bajo locales en astro.config.mjs (por ejemplo ko: { label: '한국어' }).
Crea un directorio correspondiente bajo src/content/docs/<locale>/.
Complétalo manualmente, o usa el target de traducción descrito a continuación.

Traducción

A menos que hayas pasado --noTranslation, el generador agrega un target translate a project.json, por lo que puedes ejecutar:

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

Cuando se ejecuta sin --all, el script solo traduce archivos que han cambiado desde el último commit de traducción en la rama actual — lo que significa que puedes volver a ejecutarlo de forma segura en cada PR de documentación sin volver a traducir todo el sitio.

Las traducciones cuyo archivo fuente ya no existe se eliminan, por lo que renombrar o eliminar una página no deja copias obsoletas en cada configuración regional.

Cada traducción se escribe como un archivo completo. El agente recibe el fuente, la traducción existente y un diff de lo que cambió, y reutiliza la redacción existente para las secciones que el diff dejó intactas — por lo que solo se vuelve a traducir la prosa que el diff tocó, y los bloques de código se copian del fuente tal cual.

Configurar la traducción

Edita scripts/translate.config.json para cambiar:

Campo	Propósito
`sourceLanguage`	Configuración regional desde la cual traducir (por defecto `en`).
`targetLanguages`	Configuraciones regionales a las cuales traducir. Vacío por defecto. Por ejemplo `["fr", "de", "es", "ja", "ko"]`.
`docsDir`	Ruta al directorio de contenido de documentación, relativa a la raíz del proyecto.
`include`	Patrones glob (relativos a `<docsDir>/<sourceLanguage>`) para archivos a traducir.
`exclude`	Patrones glob a omitir.
`modelId`	Modelo de Bedrock a usar para las traducciones.
`awsRegion`	Región de AWS con la que se configura el cliente de Bedrock. También se puede establecer mediante `AWS_REGION`.
`concurrency`	Número máximo de invocaciones de agente concurrentes.
`translationCommitMessage`	Marcador de mensaje de commit para commits de traducción (por defecto `docs: update translations`).

Enlaces internos conscientes de la configuración regional

El generador incluye un componente Link que resuelve automáticamente las rutas internas de documentación contra la configuración regional actual, por lo que una única fuente de verdad produce la URL correcta en cada idioma:

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

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

Fragmentos

Los fragmentos de contenido reutilizables se encuentran en src/content/docs/<locale>/snippets/. El componente Snippet generado carga el fragmento que coincide con la configuración regional actual:

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

<Snippet name="example" />

Configurar CI

No se genera ningún flujo de trabajo de CI de forma predeterminada — agrega uno que:

Configure credenciales de AWS con permiso para invocar InvokeModel de Bedrock en el modelo configurado.
Ejecute el target translate en pull requests que toquen tus documentos en el idioma fuente:
- 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
Haga commit de las traducciones resultantes de vuelta a la rama del PR. El mensaje de commit debe coincidir con el valor translationCommitMessage en scripts/translate.config.json (por defecto docs: update translations) para que las ejecuciones incrementales posteriores puedan detectar el commit de referencia y solo volver a traducir los archivos que cambiaron desde entonces.