Skip to content
@aws/nx-plugin
Blog

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

Section titled “Usage”

Generate an Astro docs site

Section titled “Generate an Astro docs site”

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

  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#astro-docs
  5. Fill in the required parameters
    • Click Generate

    Options

    Section titled “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.
    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.
    skipInstall boolean Skip installing dependencies after the generator runs.

    Generator Output

    Section titled “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

    Section titled “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

    Section titled “Translation”

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

    Terminal window
    pnpm nx translate docs -- --all
    pnpm nx translate docs -- --languages jp,ko
    pnpm 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

    Section titled “Configuring translation”

    Edit scripts/translate.config.json to change:

    FieldPurpose
    sourceLanguageLocale to translate from (default en).
    targetLanguagesLocales to translate to. Empty by default. For example ["fr", "de", "es", "ja", "ko"].
    docsDirPath to the docs content directory, relative to the project root.
    includeGlob patterns (relative to <docsDir>/<sourceLanguage>) for files to translate.
    excludeGlob patterns to skip.
    modelIdBedrock model to use for translations.
    awsRegionAWS region the Bedrock client is configured with. Can also be set via AWS_REGION.
    concurrencyMax number of concurrent agent invocations.
    translationCommitMessageCommit message marker for translation commits (default docs: update translations).
    Section titled “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

    Section titled “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

    Section titled “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:

      Terminal window
      pnpm 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.