@aws/nx-plugin 0.99.1 → 0.101.0

package/src/ts/astro-docs/files/base/README.md.template

@@ -0,0 +1,63 @@
+# <%= fullyQualifiedName %>
+
+Documentation site generated with [@aws/nx-plugin](https://github.com/awslabs/nx-plugin-for-aws/),
+powered by [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/).
+
+## Run locally
+
+```bash
+<%= pkgMgrCmd %> nx start <%= fullyQualifiedName %>
+```
+
+## Build for production
+
+```bash
+<%= pkgMgrCmd %> nx build <%= fullyQualifiedName %>
+```
+
+## Preview the production build
+
+```bash
+<%= pkgMgrCmd %> nx preview <%= fullyQualifiedName %>
+```
+<% if (includeTranslation) { %>
+## Translate documentation
+
+This project is pre-wired with a translation script that uses a
+[Strands Agent](https://strandsagents.com/) powered by Claude on
+[Amazon Bedrock](https://aws.amazon.com/bedrock/) to translate documentation from
+the source language (`en` by default) into every locale listed in
+`scripts/translate.config.json`.
+
+By default the `targetLanguages` list is empty — add the locale codes you want
+to ship, for example:
+
+```json
+"targetLanguages": ["fr", "de", "es", "ja", "ko"]
+```
+
+Make sure each locale you list is also configured in `astro.config.mjs` under
+`locales`.
+
+Run the translator manually with:
+
+```bash
+<%= pkgMgrCmd %> nx translate <%= fullyQualifiedName %> -- --all
+```
+
+Translate only the files that changed since the last `docs: update translations`
+commit:
+
+```bash
+<%= pkgMgrCmd %> nx translate <%= fullyQualifiedName %>
+```
+
+Other options in `scripts/translate.config.json`:
+
+- `include` / `exclude` — glob patterns for docs files, relative to the source
+  language directory.
+- `modelId` — Bedrock model id.
+- `awsRegion` — Bedrock region; can be overridden with the `AWS_REGION` env var.
+- `concurrency` — cap on concurrent Bedrock requests (one agent per file ×
+  target language).
+<% } %>

package/src/ts/astro-docs/files/base/astro.config.mjs.template

@@ -0,0 +1,47 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+
+import starlight from '@astrojs/starlight';
+<% if (includeBlog) { %>import starlightBlog from 'starlight-blog';
+<% } %>
+// https://astro.build/config
+export default defineConfig({
+  outDir: './dist',
+  // Redirect the root URL to the default locale so visitors land on localised content.
+  redirects: {
+    '/': '/en',
+  },
+  integrations: [
+    starlight({
+      title: '<%= title %>',
+      social: [],
+      tableOfContents: {
+        minHeadingLevel: 2,
+        maxHeadingLevel: 4,
+      },
+      defaultLocale: 'en',
+      locales: {
+        en: {
+          label: 'English',
+        },
+      },
+      sidebar: [
+        {
+          label: 'Getting started',
+          items: [{ slug: 'guides/getting-started' }],
+        },
+      ],
+      customCss: ['./src/styles/custom.css'],
+      plugins: [<% if (includeBlog) { %>
+        starlightBlog({
+          authors: {
+            default: {
+              name: 'Docs Author',
+              title: 'Maintainer',
+            },
+          },
+        }),
+      <% } %>],
+    }),
+  ],
+});

package/src/ts/astro-docs/files/base/src/components/link.astro.template

@@ -0,0 +1,25 @@
+---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { LinkButton } from '@astrojs/starlight/components';
+
+// Resolve an internal docs path against the current locale so a single source of
+// truth (the `path` prop) produces a correct URL in every language. Callers pass
+// a locale-agnostic path like `guides/getting-started`.
+const { path, type } = Astro.props;
+let resolvedPath = getRelativeLocaleUrl(Astro.currentLocale || 'en', path);
+if (resolvedPath.endsWith('/')) {
+  resolvedPath = resolvedPath.slice(0, -1);
+}
+---
+
+{
+  type === 'button' ? (
+    <LinkButton href={resolvedPath}>
+      <slot />
+    </LinkButton>
+  ) : (
+    <a href={resolvedPath}>
+      <slot />
+    </a>
+  )
+}

package/src/ts/astro-docs/files/base/src/components/snippet.astro.template

@@ -0,0 +1,20 @@
+---
+import { Aside } from '@astrojs/starlight/components';
+
+const locale = Astro.currentLocale || 'en';
+const snippets = Object.values(
+  import.meta.glob('../content/docs/*/snippets/**/*.mdx', { eager: true })
+);
+const { name } = Astro.props;
+const snippet = snippets.find((s) =>
+  s.file.endsWith(`content/docs/${locale}/snippets/${name}.mdx`)
+);
+---
+
+{
+  snippet ? (
+    <snippet.Content />
+  ) : (
+    <Aside type="danger">Unable to load snippet {name} for locale {locale}</Aside>
+  )
+}

package/src/ts/astro-docs/files/base/src/content/docs/en/blog/welcome.mdx.template

@@ -0,0 +1,13 @@
+---
+title: Welcome to <%= title %>
+date: <%= today %>
+authors:
+  - default
+---
+
+Welcome to the **<%= title %>** blog! This post was scaffolded by the
+`ts#astro-docs` generator.
+
+The blog is powered by the [`starlight-blog`](https://starlight-blog-docs.vercel.app/)
+plugin. Add new entries as MDX files under `src/content/docs/<locale>/blog/` with
+`title`, `date` and `authors` frontmatter.

package/src/ts/astro-docs/files/base/src/content/docs/en/guides/getting-started.mdx.template

@@ -0,0 +1,64 @@
+---
+title: Getting started
+description: Running your new Astro + Starlight docs site.
+---
+
+import Link from '@components/link.astro';
+import Snippet from '@components/snippet.astro';
+
+Welcome to **<%= title %>**! This site is built with [Astro](https://astro.build/) and the
+[Starlight](https://starlight.astro.build/) documentation theme.
+
+## Run locally
+
+```bash
+<%= pkgMgrCmd %> nx start <%= fullyQualifiedName %>
+```
+
+## Build for production
+
+```bash
+<%= pkgMgrCmd %> nx build <%= fullyQualifiedName %>
+```
+
+## Adding a locale
+
+Add an entry to the `locales` block in `astro.config.mjs` and create a matching
+directory under `src/content/docs/<locale>/`. Starlight will pick up the new locale
+automatically.
+<% if (includeTranslation) { %>
+:::note[Keep the translation config in sync]
+When you add a new locale, also add its code to `targetLanguages` in
+`scripts/translate.config.json` so the `translate` task will keep it up to date.
+:::
+<% } %>
+## Locale-aware links
+
+Use the generated `Link` component whenever you want to link to another page
+**inside** your docs — it automatically resolves the current locale, so a single
+source of truth produces the right URL in every language:
+
+```mdx
+import Link from '@components/link.astro';
+
+<Link path="guides/getting-started">Read the getting-started guide</Link>
+```
+
+Here is the component in action: <Link path="guides/getting-started">back to this page</Link>.
+
+For regular external links, just use ordinary Markdown `[label](url)`.
+
+## Using snippets
+
+Snippets are reusable fragments of MDX stored in `src/content/docs/<locale>/snippets/`.
+Include one in any page with the `Snippet` component:
+
+```mdx
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="example" />
+```
+
+Here is the example snippet rendered inline:
+
+<Snippet name="example" />

package/src/ts/astro-docs/files/base/src/content/docs/en/index.mdx.template

@@ -0,0 +1,29 @@
+---
+title: <%= title %>
+description: Documentation for <%= title %>.
+template: splash
+hero:
+  title: <%= title %>
+  tagline: Project documentation built with Astro and Starlight.
+  actions:
+    - text: Get started
+      link: /en/guides/getting-started
+      icon: right-arrow
+---
+
+import { CardGrid, Card } from '@astrojs/starlight/components';
+
+<CardGrid>
+  <Card title="Guides" icon="open-book">
+    Reference documentation for <%= title %>.
+  </Card>
+  <Card title="Blog" icon="pencil">
+    News and updates from the team.
+  </Card>
+  <Card title="Snippets" icon="seti:config">
+    Reusable content fragments used across the docs.
+  </Card>
+  <Card title="Localised" icon="translate">
+    Localisation is configured out of the box — add target locales in `astro.config.mjs`.
+  </Card>
+</CardGrid>

package/src/ts/astro-docs/files/base/src/content/docs/en/snippets/example.mdx.template

@@ -0,0 +1,7 @@
+---
+title: Example snippet
+---
+
+This is an **example snippet**. Snippets are reusable fragments of MDX stored
+under `src/content/docs/<locale>/snippets/`. Import them into any page with the
+`<Snippet />` component.

package/src/ts/astro-docs/files/base/src/content.config.ts.template

@@ -0,0 +1,13 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+import { blogSchema } from 'starlight-blog/schema';
+
+export const collections = {
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({
+      extend: (context) => blogSchema(context),
+    }),
+  }),
+};

package/src/ts/astro-docs/files/base/src/styles/custom.css.template

@@ -0,0 +1 @@
+/* Customise the appearance of the Starlight docs theme here. */

package/src/ts/astro-docs/files/base/tsconfig.json.template

@@ -0,0 +1,12 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@components/*": ["src/components/*"],
+      "@assets/*": ["src/content/docs/assets/*"]
+    }
+  }
+}

package/src/ts/astro-docs/files/translation/scripts/translate.config.json.template

@@ -0,0 +1,10 @@
+{
+  "sourceLanguage": "en",
+  "targetLanguages": [],
+  "docsDir": "src/content/docs",
+  "include": ["**/*.md", "**/*.mdx"],
+  "exclude": [],
+  "modelId": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+  "awsRegion": "us-west-2",
+  "concurrency": 5
+}