Astro Docs

This generator scaffolds a documentation site powered by Astro and the Starlight docs theme. It wires up localisation, reusable content snippets, locale-aware internal links and a starlight-blog plugin by default.

By default it also scaffolds an automated translation pipeline powered by a Strands Agent on Amazon Bedrock.

Usage

Generate an Astro docs site

You can generate a new Astro docs site in two ways:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#docs
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

You can also perform a dry-run to see what files would be changed

pnpm

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

yarn

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

npm

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

bun

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

Options

Parameter	Type	Default	Description
name Required	string	docs	The name of the docs project.
directory	string	.	The parent directory the docs project is placed in.
subDirectory	string	-	The sub directory the docs project is placed in. Defaults to the kebab-case project name.
framework	astro	astro	The documentation framework to use.
noTranslation	boolean		Opt out of the automated documentation translation pipeline (Strands Agent on Amazon Bedrock + a `translate` project target).
noBlog	boolean		Opt out of the `starlight-blog` plugin and the sample blog post.
preferInstallDependencies	boolean	true	Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

By default the generator creates the following project structure at docs/ in the workspace root (configurable via the name, directory and subDirectory options):

• 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

Localisation

The generator defaults to a single locale (en) and redirects the root URL to it. To add more languages:

1. Add an entry under locales in astro.config.mjs (for example ko: { label: '한국어' }).
2. Create a matching directory under src/content/docs/<locale>/.
3. Populate it manually, or use the translation target described below.

Translation

Unless you passed --noTranslation, the generator adds a translate target to project.json, so you can run:

pnpm

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

yarn

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

npm

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

bun

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

When run without --all, the script only translates files that have changed since the last translation commit on the current branch — meaning you can safely re-run it on every docs PR without re-translating the whole site.

Configuring translation

Edit scripts/translate.config.json to change:

Field	Purpose
sourceLanguage	Locale to translate from (default en).
targetLanguages	Locales to translate to. Empty by default. For example ["fr", "de", "es", "ja", "ko"].
docsDir	Path to the docs content directory, relative to the project root.
include	Glob patterns (relative to <docsDir>/<sourceLanguage>) for files to translate.
exclude	Glob patterns to skip.
modelId	Bedrock model to use for translations.
awsRegion	AWS region the Bedrock client is configured with. Can also be set via AWS_REGION.
concurrency	Max number of concurrent agent invocations.
translationCommitMessage	Commit message marker for translation commits (default docs: update translations).

Locale-aware internal links

The generator ships a Link component that automatically resolves internal docs paths against the current locale, so a single source of truth produces the right URL in every language:

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

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

Snippets

Reusable content fragments live in src/content/docs/<locale>/snippets/. The generated Snippet component loads the snippet that matches the current locale:

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

<Snippet name="example" />

Wiring up CI

No CI workflow is generated out of the box — add one that:

1. Configures AWS credentials with permission to invoke Bedrock InvokeModel on the configured model.

2. Runs the translate target on pull requests that touch your source-language docs:

   pnpm

   pnpm nx translate docs

   yarn

   yarn nx translate docs

   npm

   npx nx translate docs

   bun

   bunx nx translate docs

3. Commits the resulting translations back to the PR branch. The commit message must match the translationCommitMessage value in scripts/translate.config.json (default docs: update translations) so that subsequent incremental runs can detect the baseline commit and only re-translate the files that changed since.