# Micronaut Web
Astro prototype for three separately hostable Micronaut web surfaces:
- `main`: product entry point at `/` and `/main/`
- `docs`: platform documentation catalog and detail pages under `/docs/`
- `guides`: guides catalog and detail pages under `/guides/`
All surfaces share the same design tokens, React components, docs catalog fixture, and generated guide manifest:
```bash
npm run dev
npm run build
npm run build:main
npm run build:docs
npm run build:guides
```
`npm run check` validates TypeScript, script formatting, tests, and shared snippet styles.
`npm run sync:docs-projects` refreshes the test fixture at `src/data/docs-projects.fixture.json` from a local `micronaut-projects/micronaut-platform` checkout's `gradle/libs.versions.toml` plus the metadata already stored in the fixture.
`src/data/docs-projects.fixture.json` is the checked-in docs project metadata source so CI can run the docs renderer without an external metadata checkout.
`npm run build` also prepares plain HTML template artifacts under `dist/micronaut-web`.
## Script Development
All repository scripts under `scripts/` must be TypeScript files. Add new scripts as `.ts`, import other local script modules with `.ts` extensions, invoke them from `package.json` with `node scripts/...ts` or `node --test scripts/tests/...test.ts`, and keep the full `npm run typecheck:scripts` TypeScript check passing. The script check uses strict TypeScript settings and non-pretty compiler output for CI logs. Formatting is checked with `npm run style`, which covers `scripts/`, `src/` and `tests/` (`.ts`, `.tsx`, `.astro`) plus `astro.config.mjs`; `npm run style:fix` rewrites them. Node 24 or newer is assumed for direct TypeScript script execution, matching CI.
### Package Scripts
| Script | Purpose |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `npm run check` | Runs TypeScript checks, script formatting, script tests, browser-backed surface tests, and snippet style validation. |
| `npm run snippet-styles` | Verifies generated docs snippet styles stay shared instead of copied into runtime layout code. |
| `npm run sync:docs-projects` | Refreshes `src/data/docs-projects.fixture.json` from a local Micronaut Platform checkout. |
| `npm run render:docs` | Renders generated docs fragments and the docs project catalog. |
| `npm run render:guides` | Renders generated guide fragments and the guide manifest. |
| `npm run prepare:generated-docs` | Alias for `render:docs`, used by docs preparation flows. |
| `npm run prepare:generated-content` | Renders docs and guides generated content together. |
| `npm run test:main-site` | Runs main-site script tests and the main-site Playwright wrapper. |
| `npm run test:main-site:browser` | Runs the main-site Playwright spec directly. |
| `npm run test:asciidoc` | Runs shared Asciidoc renderer and macro tests. |
| `npm run test:docs` | Runs docs script tests and the docs Playwright wrapper. |
| `npm run test:docs:browser` | Prepares docs generated content and runs the docs Playwright spec. |
| `npm run test:guides` | Runs guides script tests and the guides Playwright wrapper. |
| `npm run test:guides:browser` | Prepares guides generated content and runs the guides Playwright spec. |
| `npm run test:deployment` | Runs deployment, pruning, publishing, and surface-routing script tests. |
| `npm run typecheck` | Runs the main TypeScript project check. |
| `npm run typecheck:scripts` | Runs the strict TypeScript check for files under `scripts/`. |
| `npm run style` | Checks `scripts/`, `src/` and `tests/` formatting with Prettier. |
| `npm run style:fix` | Rewrites those files with Prettier. |
| `npm run dev` | Runs the full check, prepares generated content, and starts Astro dev on `127.0.0.1`. |
| `npm run build:site` | Runs checks, prepares generated content, builds Astro, builds the shared header shell, and prepares template artifacts. |
| `npm run build` | Same as `build:site`; kept as the default full-site build command. |
| `npm run build:surface` | Builds and prunes a selected deployment surface. |
| `npm run build:main` | Builds the standalone main surface. |
| `npm run build:docs` | Builds the standalone docs surface. |
| `npm run build:guides` | Builds the standalone guides surface. |
| `npm run prune:surface` | Prunes an existing `dist` output for the selected surface. |
| `npm run update:docs-versions` | Rebuilds the published docs version manifest. |
| `npm run publish:docs-surface` | Merges a docs surface build into an existing published docs tree. |
| `npm run preview` | Runs `astro preview` on `127.0.0.1`. |
## Design Tokens
The shared palette intentionally follows the classic micronaut.io direction:
- black hero and footer surfaces
- white content areas
- Micronaut blue for primary CTAs, active states, links, and section bands
- restrained cool gray borders and muted text
- near-black code panels
The logo must stay black on light surfaces and white on dark surfaces. Do not recolor Micronaut logos with blue or other accents; use blue for UI treatments around the brand, not for the mark itself.
Core brand tokens live in `src/styles/globals.css`:
```text
Brand black: #000000
Brand white: #ffffff
Micronaut blue: #2f73b9
Classic site blue: #337ab7
Blue hover: #245e99
Blue deep: #173f67
Blue soft: #eaf3fb
Light border: #d9e1e8
Dark background: #050505
Dark surface: #111111
Dark blue: #66a9e6
```
Tailwind can access the extra Micronaut-specific variables through the `@theme inline` mappings, for example `bg-micronaut-blue`, `text-micronaut-blue-deep`, `bg-hero`, `bg-blue-band`, and `bg-code`.
## Content Catalogs
`src/data/docs-projects.fixture.json` contains the checked-in docs project catalog, categories, descriptions, repository links, and platform versions used when generated docs output is unavailable.
`src/data/generated-guides.fixture.json` contains the checked-in guide catalog subset used when generated guide output is unavailable. `src/content/generated-guides/manifest.json` is produced by `npm run render:guides` and ignored as generated content.
A guide's snippets resolve against the guide's own directory and, when it exists, the sample project the guides build writes to `build/code/<slug>/<slug>-<build tool>-<language>` in the guides checkout. That project is the `sourcedir` the upstream Asciidoctor build uses, and it is the only place to read the Micronaut Starter files a guide never checks in, such as the application class, the generated configuration, and the build scripts. `npm run render:guides` works without it; only those Starter snippets stay unresolved. Publishing generates it with `./gradlew generateCodeZip`, which also writes the per-variant archives each guide links as its download. A guide is never offered as a Maven and Kotlin variant, because the guides build refuses to generate that combination.
## Blog Authoring
### Blog Posts
Blog posts are Astro Markdown content entries under `src/content/main-site/blog`. Use a dated path that mirrors the public slug, for example `src/content/main-site/blog/2026/06/01/example-post.md`. The `slug` frontmatter field is the canonical route without leading or trailing slashes; `href` defaults to `/${slug}/`, so set `href` only when a post needs an explicit canonical override.
Use this shape for a normal post:
````md
---
slug: 2026/06/01/example-post
title: Example Post Title
description: One or two sentences used in cards, metadata, and search previews.
date: "2026-06-01T09:00:00"
modified: "2026-06-01T09:00:00"
category: release-announcements
categories:
- release-announcements
tags:
- release
href: /2026/06/01/example-post/
---
Opening paragraph for the post.
## Section Heading
Body copy can use normal Markdown.
```java
class Example {
}
```
````
Required blog fields are `slug`, `title`, and `description`. Dates are optional in the schema, but new posts should set `date` so sorting is predictable; set `modified` when the published content changes after the initial date. `order` is an optional tie-breaker when posts have the same date. `sourceUrl`, `wordpressId`, and `contentSource: wordpress-post` are migration metadata for imported posts and are not required for newly authored content.
The Markdown body is rendered through Astro and then passed through the main-site Markdown renderer. Headings, paragraphs, links, lists, blockquotes, tables, horizontal rules, images, inline code, and fenced code blocks are supported. Fenced code blocks are converted to the shared docs snippet card style; prefer a language marker such as `java`, `kotlin`, `groovy`, `bash`, `xml`, `yaml`, or `gradle`. Some obvious Java, Gradle, and XML snippets can be inferred when the fence has no language, but explicit language markers are easier to maintain.
Use root-relative links for internal routes, such as `/docs/`, `/guides/`, or `/2026/06/01/example-post/`. Links and images pointing at `https://micronaut.io/...` or root-relative Micronaut paths are rewritten through the deployment base-path helpers during rendering. For local images and downloads, put source files under `public/micronaut-assets/main-site/...` and reference them from Markdown with `/micronaut-assets/main-site/...`. Image Markdown should include useful alt text.
### Main-Site Pages
Main-site pages are Markdown content entries under `src/content/main-site/pages`. The route is derived from the file path under that directory: `support.md` becomes `/support/`, `brand-guidelines/micronaut-logos.md` becomes `/brand-guidelines/micronaut-logos/`, `category/release-announcements.md` becomes `/category/release-announcements/`, and an `index.md` file drops the final `index` segment.
Use this shape for a normal page:
```md
---
order: 12
title: Example Page
eyebrow: Resources
description: One or two sentences used in cards, metadata, and search previews.
sourceUrl: https://micronaut.io/example/
intro: Optional short lead text for the page header.
redirectFrom:
- /old-example/
---
# Example Page
Normal Markdown page content.
```
Required page fields are `order`, `title`, `eyebrow`, `description`, and `sourceUrl`. `intro` feeds the shared main-site page header for authored pages; body Markdown is rendered as page content for normal pages. `redirectFrom` lists old paths that should redirect to the new route. Adding a page makes the route available and searchable, but it does not automatically add the page to the header or footer; update the relevant navigation data when a new page should be linked globally.
Use `layoutVariant: public-markdown` only for imported public `micronaut.io` Markdown pages whose body already carries the page heading or whose route has special archive/FAQ rendering. This layout variant uses the full main-site content width and suppresses the generated wrapper header for ordinary pages. Omit `layoutVariant` for newly authored pages so they use the default narrower article layout with the generated badge, title, and intro header.
### Blog Categories and Archives
`category` is the primary category slug. It is shown on blog cards and is used by `/category/<slug>/` archive pages. `categories` is an additional list of category slugs; include the primary category there as well so archive membership stays consistent with older imported posts. Category slugs are lower-case kebab-case strings. Existing category pages are:
- `case-studies`
- `guest-post`
- `microcast`
- `micronaut-4`
- `micronaut-5`
- `micronaut-framework-2`
- `release-announcements`
- `security-announcements`
- `sponsor`
- `town-hall-meetings`
- `uncategorized`
- `webinar`
Category archive routes are page-backed. Post metadata decides membership, but it does not create the public category page by itself. To introduce a new public category:
1. Choose a lower-case kebab-case slug, for example `micronaut-6`.
2. Set the post `category` to that slug and include the same slug in `categories`.
3. Add `src/content/main-site/pages/category/<slug>.md` with the normal main-site page frontmatter so `/category/<slug>/` has a title, intro, sections, metadata, and archive content.
4. Add the page to footer or header navigation only when it should be linked globally.
The category archive lists posts whose primary `category` matches the slug or whose `categories` array contains it. The `/blog/` page lists the first 24 regular posts, `/blog/page/<n>/` pages are generated from the post count, and the `success-story` category is excluded from the regular blog archive.
`tags` are lower-case kebab-case slugs used for `/tag/<tag>/` archive routes. Tag archive routes are generated from post metadata and do not require separate page files. The global search dialog indexes main-site pages, docs, guides, and guide tags; blog category and tag archives are normal static routes rather than a separate external search service.
Dated blog slugs automatically get legacy redirects from `/blog/YYYY-MM-DD-post-slug.html` to the canonical dated route. Explicit historical aliases live in `src/lib/blog-redirects.ts`; add there only when an old WordPress URL does not match the generated dated redirect. The `success-story` category is special-cased out of the regular `/blog/` listing; new production stories should normally be authored as pages under `src/content/main-site/pages/micronaut-success-stories/` instead of as blog posts.
## Search
Search is static and catalog-backed. There is no external search service; the UI searches data already shipped in the current surface artifact.
The header search is `SearchDialog`, rendered by `SiteHeader` in the top-menu island and hydrated on load. It opens from the search button or the `Meta/Ctrl+K` keyboard shortcut, then navigates by assigning `window.location.href` through the base-path helpers so the same result paths work in the all-in-one preview, standalone docs, standalone guides, remote-header shells, and GitHub Pages base paths.
The main-site search mode is used on the main and guides surfaces. Its result sets come from:
- `getMainSitePageSummaries()`, passed into `SiteHeader`, for main-site pages. These are available synchronously.
- `/search-index.json`, fetched when the dialog first opens. `src/pages/search-index.json.ts` prerenders it from `searchItems()` in `src/lib/content-catalog.ts`, which is backed by `src/data/docs-projects.fixture.json` for docs projects and synthetic docs sections and by `src/data/generated-guides.fixture.json` for guides and guide tags.
Neither catalog is imported into the dialog. `SiteHeader` is hydrated on every page, so a static import would ship both fixtures (roughly 92 KB) to every visitor whether or not search is ever opened.
Main-site search groups results into actions, main-site pages, docs and APIs, guides, and tags. Each command item exposes a searchable value made from its kind, title, description, and terms; the `cmdk` command component handles the visible filtering. The source groups are capped before rendering to keep the dialog small: up to 80 main-site pages, 80 docs entries, 80 guide entries, and 40 tags. This mode does not read generated docs HTML, so deep generated headings, configuration properties, and API classes are available only in docs search mode.
Docs search mode is used when `SiteHeader` is rendered with `surface="docs"`. On open it fetches the configured docs search index URL or `withBasePath("/docs/search-index.json")`. In standalone docs deployments that path is routed to `/<line>/search-index.json`; in the all-in-one preview it stays under `/docs/search-index.json`. `WebLayout` passes both index URLs (`docsSearchIndexUrl`, `siteSearchIndexUrl`) as absolute surface URLs, and the remote header shell reads them from `data-docs-search-index-url` and `data-site-search-index-url`. If a fetch fails the dialog shows no catalog results; main-site pages stay searchable.
The docs search index route is `src/pages/docs/[searchIndex].json.ts`. It is prerendered only when docs routes are enabled and returns JSON as `{ "items": [...] }`; because it is prerendered, only the body is emitted and response headers come from the host serving the artifact. It loads the docs project catalog from `src/content/generated-docs/project-catalog.json` when present, otherwise from `src/data/docs-projects.fixture.json`, then reads generated HTML from `src/content/generated-docs/*.html` and calls `buildDocsSearchIndex(...)` in `scripts/docs/search-index.ts`.
`buildDocsSearchIndex(...)` emits project, docs section, and repository items for every project, then extracts richer generated-doc entries from HTML:
- `h1` and `h2` headings inside `.guide-section-heading` become docs results.
- Table rows whose first cell looks like a configuration property become property results.
- Links to generated `/api/*.html` pages become class results.
Generated entries are deduplicated by scope, href, and title, and each project is capped at 1200 generated items. Docs search adds scope chips for all results, projects, docs, properties, classes, and repositories, then filters by lower-case substring over kind, title, description, and terms before rendering up to 240 results.
Guides catalog filtering is separate from the header dialog. `LatestGuidesCatalog` reads URL parameters on the server: `q` matches guide title, intro, authors, categories, and tags; `category` and `tag` narrow the list; and `sort` accepts `latest`, `title`, or `duration`. Filter links are generated with `filterHref(...)`, so the selected filters remain URL-addressable.
## Deployment and Compatibility
This repository is the only source implementation for the three web surfaces. A normal Astro build can render the all-in-one preview, then `scripts/prune-surface.ts` rewrites that full `dist` output into the artifact shape needed by one deploy target.
Production-compatible hosts are:
- `main`: `https://micronaut.io/`
- `docs`: `https://docs.micronaut.io/`
- `guides`: `https://guides.micronaut.io/`
Temporary GitHub Pages hosts keep the repository names in the path:
- `micronaut-web`: main site at `/micronaut-web/`
- `micronaut-docs-v2`: docs selector at `/micronaut-docs-v2/`, release-line folders such as `/micronaut-docs-v2/5.0.x/`, and `/micronaut-docs-v2/latest/` redirecting to the newest of them
- `micronaut-docs-snapshot`: snapshot docs at `/micronaut-docs-snapshot/snapshot/`
- `micronaut-guides-v2`: guides at `/micronaut-guides-v2/`
### Surface Split
Surface builds are selected with `MICRONAUT_DEPLOY_SURFACE=main|docs|guides`. `scripts/build-surface.ts` sets a matching default `ASTRO_BASE`, runs the full static build, then prunes the artifact:
- `npm run build:main` keeps the homepage, blog/content pages, redirects, `.nojekyll`, shared branding assets, and the shared header shell under `/shell/site-header.js` and `/shell/site-header.css`. It sets `MICRONAUT_PREPARE_GENERATED_CONTENT=false` by default, so the web deployment does not fetch or render docs/guides content. Dynamic docs/guides route generation is disabled for this surface, and pruning removes any remaining docs, guides, latest-route, and template artifacts from the published Pages artifact.
- `npm run build:docs` keeps the docs index, docs project pages, search index, docs version selector, docs redirects, `_astro`, `.nojekyll`, and shared docs assets. It prepares only generated docs content and removes unrelated main and guides route trees.
- `npm run build:guides` renders the generated guides once under `/guides`, moves that tree to `/latest` for the standalone guides artifact, and keeps the root redirect, guide compatibility routes, `_astro`, `.nojekyll`, and shared guide assets. It prepares only generated guides content and removes unrelated main and docs route trees.
Every surface publishes its own `robots.txt` and sitemap. `src/pages/robots.txt.ts` resolves the `Sitemap:` line from that build's site and base, and `@astrojs/sitemap` is filtered to the pages that survive pruning and serialized to the paths they are served from, so the docs sitemap lists `/<line>/<project>/` and the guides sitemap lists root-level guides. Pages that ask to stay out of search results are dropped as well: the filter reads the built HTML back and skips anything carrying a `robots` `noindex` meta, which covers both the refresh stubs Astro emits for `Astro.redirect()` and pages passing `noindex` to `WebLayout`. Both files are written to the build root, so `scripts/prune-surface.ts` and `scripts/publish-docs-surface.ts` carry them across through `scripts/shared/crawler-files.ts`.
Standalone docs and guides builds do not publish their own header shell. In production they render a small static fallback header, load the header stylesheet and React shell from the configured main-site URL, then mount the current `SiteHeader` implementation from `micronaut-web`. This keeps the top navigation owned by the web repository even when docs and guides content are generated from separate repositories. The fallback links use `MICRONAUT_MAIN_SITE_URL`, `MICRONAUT_DOCS_SITE_URL`, and `MICRONAUT_GUIDES_SITE_URL`, so split-repo Pages deployments can point at the correct published artifacts without hard-coded repository names.
### GitHub Actions
| Workflow | Trigger | Summary |
| --- | --- | --- |
| [`Validate Build`](.github/workflows/validate-build.yml) | Pull requests | Checks script formatting and builds the docs, guides, and main-site surfaces. Generated external content is disabled for this validation build. |
| [`Deploy Web`](.github/workflows/deploy-web.yml) | Pushes to `main` or manual dispatch | Builds only the web surface, ensures `dist/.nojekyll` is present, uploads the pruned artifact, and deploys it with GitHub Pages Actions. It does not check out Micronaut Platform or Micronaut Guides. |
| [`Deploy Docs`](.github/workflows/deploy-docs.yml) | Manual dispatch or a `platform-released` repository-dispatch event | Builds one Docs release from Micronaut Platform and publishes it to `micronaut-projects/micronaut-docs-v2:gh-pages` under its release line, for example `5.0.3` to `/5.0.x/`. Manual runs take only `docs_version`; a platform release also supplies the exact source revision. `/latest` redirects to the newest published line. |
| [`Deploy Guides`](.github/workflows/deploy-guides.yml) | Manual dispatch or a `guides-updated` repository-dispatch event | Runs the guides project's own Gradle build to generate the sample projects and their downloadable archives, renders the guides against them, and publishes everything to `micronaut-projects/micronaut-guides-v2:gh-pages`. Manual runs choose the source with `guides_repository` and `guides_ref`; a `guides-updated` event uses `client_payload.sha` to publish the exact upstream commit. |
| [`Deploy Snapshot Docs`](.github/workflows/deploy-docs-snapshot.yml) | Manual dispatch | Builds the docs from the Micronaut Platform default branch and force-pushes them to `micronaut-projects/micronaut-docs-snapshot:gh-pages` as a single commit, then refreshes the `/snapshot` entry on the released docs branch. |
| [`Publish Upstream Updates`](.github/workflows/publish-upstream-updates.yml) | Hourly schedule or manual dispatch | Polls Micronaut Platform and Micronaut Guides, then starts `Deploy Docs` for platform releases that are not published yet, `Deploy Snapshot Docs` when the platform default branch has moved, and `Deploy Guides` when guides `master` has moved. |
The web target uses GitHub Pages Actions deployment from the uploaded `dist` artifact. The docs and guides Pages targets branch-deploy to `micronaut-projects/micronaut-docs-v2:gh-pages` and `micronaut-projects/micronaut-guides-v2:gh-pages`. Those destinations are workflow-level constants rather than inputs, so a publish cannot be pointed at another branch by accident.
The web workflow uses the repository's GitHub Pages Actions permissions (`pages:write` and `id-token:write`) and does not need a branch-publish token. Docs and guides push to a different repository, so both require `GH_TOKEN` with `contents:write` access to their publication target.
External source repositories checked out by the manual docs and guides workflows are placed under `external/` in the GitHub workspace. `actions/checkout` paths must stay inside the workspace; do not use `${{ runner.temp }}` for those checkouts.
The docs workflow resolves the Platform ref explicitly as a branch first, then as an exact tag, then as a `v`-prefixed tag such as `v4.10.14`, and finally as a raw Git ref or SHA. The ref comes from `client_payload.sha` on a platform release and otherwise from `docs_version`, so publishing `docs_version=4.10.14` resolves the Platform tag `v4.10.14`.
### Routing Inputs
The build reads these deployment inputs:
- `ASTRO_BASE`: deployment path used for pages and assets, such as `/micronaut-web/`, `/micronaut-docs-v2/`, or `/micronaut-guides-v2/`. Docs and guides workflows derive it from their publication repository; an existing or configured custom domain uses `/`.
- `MICRONAUT_DEPLOY_SURFACE`: active surface, one of `main`, `docs`, `guides`, or `all`.
- `MICRONAUT_DOCS_ROOT`: docs root in the current artifact. It is `/docs` for all-in-one preview, `/<major>.<minor>.x` for a published docs release, and `/latest` for a local standalone docs build.
- `MICRONAUT_DOCS_LATEST_ROOT`: latest docs root, normally `/latest`.
- `MICRONAUT_GUIDES_ROOT`: public guides root in the current artifact. Source guide pages are authored under `/guides`; standalone guides builds publish that rendered tree at `/latest`.
- `MICRONAUT_GUIDES_LATEST_ROOT`: latest guides root, normally `/latest`.
- `MICRONAUT_PREPARE_GENERATED_CONTENT`: set to `false`, `0`, or `none` to skip generated docs/guides rendering before Astro starts. `build:main` sets this to `false` by default; docs and guides builds leave it enabled but prepare only the generated content for their own surface.
- `DEFAULT_GITHUB_PAGES_ORIGIN`: computed by GitHub Actions from the workflow repository owner, for example `https://${GITHUB_REPOSITORY_OWNER}.github.io`. The current docs or guides surface URL is derived separately from the publication repository.
- `MICRONAUT_GITHUB_PAGES_ORIGIN`: effective GitHub Pages host override. When unset, it falls back to `DEFAULT_GITHUB_PAGES_ORIGIN`.
- `MICRONAUT_MAIN_SITE_URL`, `MICRONAUT_DOCS_SITE_URL`, `MICRONAUT_GUIDES_SITE_URL`: optional complete surface URL overrides. In docs and guides workflows, the active surface is derived from the publication repository or its custom domain; remaining defaults use `MICRONAUT_GITHUB_PAGES_ORIGIN` plus the repository name.
- `MICRONAUT_DOCS_BASE`, `MICRONAUT_GUIDES_BASE`: optional repository variables that override the derived docs or guides deployment base.
- `MICRONAUT_DOCS_CUSTOM_DOMAIN`, `MICRONAUT_GUIDES_CUSTOM_DOMAIN`: optional repository variables used when creating a custom-domain deployment. For branch deployments, an existing root `CNAME` is detected automatically and preserved.
- `MICRONAUT_DOCS_SNAPSHOT_SITE_URL`, `MICRONAUT_DOCS_SNAPSHOT_CUSTOM_DOMAIN`, `MICRONAUT_DOCS_SNAPSHOT_BASE`: optional repository variables for the snapshot docs deployment. They stand in for the docs surface variables in `Deploy Snapshot Docs`, whose docs site is the snapshot deployment rather than the released docs host.
All app links should go through `src/lib/base-path.ts` or `src/lib/deployment-config.ts`. Those helpers translate `/docs`, `/guides`, and `/latest` links so the same source can run as an all-in-one preview, standalone docs, standalone guides, or the main site linking to external docs/guides.
### Docs Versions and Latest
Docs are versioned by release line. The docs publish workflow takes a single input, `docs_version`, for example `4.10.14`. It also accepts a `platform-released` repository-dispatch event from Micronaut Platform with a `client_payload.version` in the same format and an optional `client_payload.sha` for the exact source revision. A version may carry a prerelease suffix, such as `5.2.0-M1`.
Each release is published under its `major.minor.x` line, so `5.0.3` replaces the `/5.0.x/` tree `5.0.2` published. A reader's bookmark survives every patch and only has to move when they follow a new minor. `/latest` is never a copy of the docs: it is a tree of redirects onto the newest line, so opening `/latest/core/` lands on `/5.2.x/core/` and the URL that gets shared, indexed, and bookmarked names the line the docs came from.
The docs workflow:
1. Checks out this repository.
2. Checks out `micronaut-projects/micronaut-docs-v2` on `gh-pages`.
3. Checks out the requested Micronaut Platform ref for docs sources and metadata.
4. Resolves the release line for `docs_version` and refuses the run when that line already publishes a newer release, so a replayed or re-dispatched release event cannot downgrade published docs. Every publication moves `/latest` only when the version is newer than every retained Platform version, so a later v4 publication cannot replace a v5 `/latest`, and a republish of an older line leaves `/latest` alone.
5. Runs `scripts/update-docs-version-manifest.ts` against the existing published branch. This rebuilds the selector data from the published lines plus the line currently being published. Because a line folder is named after the line and not the patch inside it, each entry also records the `release` it was built from, and the selector shows that release — `5.0.3`, not `5.0.x` — so a reader is told which docs they are actually reading. A line published before the manifest recorded a release falls back to naming itself.
6. Builds a docs surface with `MICRONAUT_DOCS_ROOT=/${docs_line}` and `MICRONAUT_DOCS_LATEST_ROOT=/latest`.
7. Runs `scripts/publish-docs-surface.ts` to merge the new version into the published branch.
8. Commits and pushes the branch.
The docs merge stores deployment metadata with the published artifact. If the base or complete surface URLs change, retained version HTML and text assets are migrated to the new deployment values before unused shared assets are pruned. This allows a one-time move from the repository-path Pages URL to a root custom domain without rebuilding every historical docs source.
The docs workflow does not check out or render Micronaut Guides.
`.github/workflows/publish-upstream-updates.yml` covers the fact that GitHub Actions cannot subscribe to events in another repository. It runs hourly and can also be started manually. For docs it lists the newest stable patch of every Micronaut Platform major/minor line, then publishes a release only when it supersedes the newest published patch of its own line or opens a line newer than everything published, so major/minor lines that were never published stay unpublished. Each version is dispatched to `Deploy Docs` oldest first, waiting for the previous publish because a queued run in the `docs-pages` concurrency group is cancelled when a newer one joins it. For guides it compares `.guides-revision` on the guides Pages branch, written by `Deploy Guides` with the revision it built, against `master` in `micronaut-projects/micronaut-guides`, and dispatches `Deploy Guides` for the exact upstream commit when they differ. For snapshot docs it compares `.platform-revision` on the snapshot Pages branch against the platform default branch and dispatches `Deploy Snapshot Docs` for the exact upstream commit when they differ, after the release publishes of the same run, because both publishes push the released docs branch. Once Micronaut Platform and Micronaut Guides send `platform-released` and `guides-updated` repository-dispatch events, this workflow becomes a safety net rather than the primary trigger.
`.github/workflows/republish-published-docs.yml` is a manual-only workflow for occasional full refreshes, such as a base-path or shared-asset migration. It is deliberately not scheduled, because a full republish rebuilds every retained line. It reads the releases recorded in the published `versions.json` together with any exact-version folders left from before docs moved to release lines, sorts them from oldest to newest, and rebuilds them one at a time. Each rebuild waits for the preceding docs publish workflow to succeed before starting, so shared Pages assets and the version manifest are updated deterministically. Only the final, newest version refreshes `/latest`, because `Deploy Docs` moves `/latest` solely for the newest published version.
The published docs branch layout is:
- `/index.html`: docs selector/index.
- `/versions.json`: compact selector data for published versions. `scripts/update-docs-version-manifest.ts` regenerates `src/data/docs-versions.json` from the published docs branch during a docs deploy; the tracked copy is only the static fallback the selector renders before that fetch resolves, so it deliberately carries no patch version and must not be updated per release.
- `/latest/<page>/`: redirect onto the same page of the newest published line. Every page of that line is mirrored, so historical `/latest/...` links keep working; `/latest/guide/` is the compatibility alias for Core docs and redirects straight to `/<line>/core/`.
- `/latest.html`: redirect to the newest published line.
- `/snapshot/<page>/`: redirect onto the same page of the snapshot Pages site, refreshed by `Deploy Snapshot Docs`.
- `/<major>.<minor>.x/`: docs tree for a published release line, replaced by each new patch of that line.
- `/<major>.<minor>.x.html`: compatibility redirect to `/<major>.<minor>.x/`.
- `/<version>/` and `/<version>.html`: redirects to the line that replaced an exact version published before docs moved to release lines.
- `/_astro/`: Astro-generated scripts and styles.
- `/assets/<hash>/...`: shared generated content assets.
- `/assets/...` and `/docsassets/...`: preserved upstream docs assets when already present in the published branch.
Older lines are not copied into new builds. They remain in `gh-pages` from previous publishes, and the selector links to those existing line folders or legacy external URLs.
### Docs Snapshot
Snapshot docs are the same docs surface built from the Micronaut Platform default branch instead of a release. `DOCS_SNAPSHOT_SOURCES=true` renders every project the catalog names from its own default branch, the branch each project publishes its own snapshot documentation from, rather than from the release tag the catalog pins. Each project then reports the version that branch builds, read from its `gradle.properties`, so the pages, the project cards, and the source links all describe the unreleased sources.
They are published to `micronaut-projects/micronaut-docs-snapshot` on `gh-pages`, as a single force-pushed orphan commit. The tree is rebuilt whenever upstream moves, so keeping its history would add a full docs tree to the repository several times a week; the branch therefore carries exactly one commit, plus a `.platform-revision` marker recording the built revision. `Publish Upstream Updates` compares that marker with the platform default branch and starts `Deploy Snapshot Docs` when they differ, the same way it polls guides.
A GitHub Pages host serves exactly one repository, so `https://docs.micronaut.io/snapshot/` cannot be the snapshot repository's tree. `Deploy Snapshot Docs` mirrors the pages it built into `/snapshot/` on the released docs branch as redirect stubs onto the snapshot Pages site, page for page, the way `/latest` mirrors the newest release line. `scripts/publish-docs-snapshot.ts` writes that mirror; the stubs preserve the query and fragment, so a deep link such as `/snapshot/guide/#nettyClientPipeline` lands on the same anchor of the snapshot site. A stub never reuses the destination of a page that is itself a redirect, because a destination inside the snapshot tree is resolved against the snapshot deployment base, which does not exist on the released docs host.
Both this workflow and `Deploy Docs` push the released docs branch, so `Deploy Snapshot Docs` shares the `docs-pages` concurrency group, and the poller dispatches it only after the release publishes of the same run have finished.
Snapshot deployment values default to the publication repository: `https://micronaut-projects.github.io/micronaut-docs-snapshot/` with base `/micronaut-docs-snapshot/`. `MICRONAUT_DOCS_SNAPSHOT_SITE_URL`, `MICRONAUT_DOCS_SNAPSHOT_CUSTOM_DOMAIN`, and `MICRONAUT_DOCS_SNAPSHOT_BASE` override them; an existing `CNAME` on the snapshot branch is read back before the force push and preserved.
The published snapshot branch layout is:
- `/index.html`: docs selector/index.
- `/snapshot/<project>/`: snapshot docs tree.
- `/snapshot.html`: compatibility redirect to `/snapshot/`.
- `/.platform-revision`: the platform revision this snapshot was built from.
- `/_astro/` and `/assets/<hash>/...`: Astro-generated and shared generated content assets.
### Guides Latest
Guides are currently published as a latest-only surface. The guides workflow accepts the guides repository/ref to build from, checks out `micronaut-projects/micronaut-guides-v2` on `gh-pages`, builds `npm run build:guides`, replaces the published branch contents with the pruned `dist` plus a `.guides-revision` marker recording the built commit, and pushes `gh-pages`. It does not check out Micronaut Platform or render generated docs.
The published guides branch layout is:
- `/index.html`: redirect to `/latest/`.
- `/latest/`: latest guides catalog and generated guide pages.
- `/latest/index.html`: compatibility entry point.
- `/latest/<guide>/`: guide overview or detail pages.
- `/_astro/`: Astro-generated scripts and styles.
- `/assets/<hash>/...`: shared generated guide content assets.
Guide ZIP downloads stay as redirects to the production guide ZIP URLs instead of storing ZIP payloads in the GitHub Pages branch.
### Shared Assets
There are three asset groups:
- `_astro`: Astro-generated JavaScript and CSS. Surface pruning preserves reachable files in this folder, removes unreferenced chunks, and writes `.nojekyll` so GitHub Pages serves underscore-prefixed paths.
- `public/micronaut-assets`: source-controlled brand, icon, and main-site assets. The main surface serves all of them; `micronaut-assets/icons/` is also copied into the docs and guides artifacts by `prune-surface.ts`, because the docs index renders one icon per project and should not fetch above-the-fold imagery from the main-site origin. `surface-path-rules.ts` keeps those paths surface-local; everything else under `micronaut-assets/` resolves to the main site.
- Generated docs/guides content assets: images and copied resources produced under generated `assets` folders before pruning.
Docs and guides surface pruning hoists generated docs/guides content assets out of version folders into content-addressed `/assets/<hash>/...` folders, then rewrites generated HTML to reference those shared files. The hash is based on file content, so identical assets across versions share one folder instead of being duplicated under every version. Docs publication preserves referenced shared hash folders and removes unreferenced generated hash folders so old assets do not accumulate unnecessarily.
### UX And Compatibility Contract
This section is the maintainer-facing contract for Micronaut web UI/UX work, legacy URL handling, and production host mapping.
#### PageSpeed Baselines
Observed baselines before the compatibility pass:
| Surface | URL | Form factor | Performance | Accessibility | Best Practices | SEO | Notes |
| ---------- | ----------------------------------------------------------- | ----------- | ---------------------------------------: | ---------------------------------------: | ---------------------------------------: | ---------------------------------------: | ------------------------------------------------------------------------------------- |
| Homepage | `${MICRONAUT_GITHUB_PAGES_ORIGIN}/micronaut-web/` | Desktop | 100 | 93 | 100 | 100 | Main issues were shared link naming and low-contrast brand opacity patterns. |
| Homepage | `${MICRONAUT_GITHUB_PAGES_ORIGIN}/micronaut-web/` | Mobile | 96 | 93 | 100 | 100 | Cache lifetime is partly hosting-controlled. |
| Docs index | `${MICRONAUT_GITHUB_PAGES_ORIGIN}/micronaut-web/docs/` | Mobile | 93 | 95 | 100 | 100 | Main issues were unnamed generated anchors, image dimensions, and unused hydrated JS. |
| Core docs | `${MICRONAUT_GITHUB_PAGES_ORIGIN}/micronaut-web/docs/core/` | Desktop | Needs re-run after generated docs render | Needs re-run after generated docs render | Needs re-run after generated docs render | Needs re-run after generated docs render | Core is the heaviest generated page and the main DOM-size/performance risk. |
Known Core docs findings:
- The generated Core page can exceed 100k DOM nodes when the full guide is rendered.
- Generated heading anchor links must have accessible names.
- Generated docs images should have stable dimensions or get dimensions attached once loaded.
- Render-blocking and unused JavaScript should be reduced by keeping static page chrome server-rendered where possible and hydrating only interactive controllers.
#### UI/UX Findings And Intended Fixes
- Header and footer logo links need explicit accessible names because the visual logo image is decorative.
- Generated heading anchors need `aria-label` values derived from heading text.
- Repeated generic links such as guide card "Read" actions need item-specific labels.
- Brand-colored text should not rely on reduced opacity where that can lower contrast.
- Logos, project icons, customer logos, language icons, and generated docs images need stable sizing to reduce layout shift.
- Docs/Core should favor readable generated content, a predictable sidebar, and active section state without making the generated article part of a large hydrated island.
- Guides index must remain available at `/latest/index.html` and support URL-backed filtering with `q`, `category`, `tag`, and `sort`.
#### Compatibility Manifest Schema
Route aliases and redirects should be added through `src/lib/route-compatibility.ts` so compatibility remains centralized.
Each route compatibility entry has:
| Field | Purpose |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Stable identifier used by tests and route modules. |
| `sourceSurface` | Surface receiving the legacy URL: `main`, `docs`, `guides`, or `assets`. |
| `sourcePath` | Representative legacy path, with `{placeholder}` markers for route families. |
| `destinationSurface` | Surface that owns the canonical destination. |
| `previewDestinationPath` | All-in-one preview target, before `ASTRO_BASE` is applied. |
| `productionDestinationPath` | Production target path on `destinationSurface`. |
| `status` | Expected status for redirect-style routes, or `200` for production aliases. |
| `behavior` | `canonical`, `redirect`, `external-redirect`, or `alias`. |
| `preservesSearch` | Whether query strings are expected to survive the redirect. |
| `preservesHash` | `client`, `same-document`, or `not-available`. URL fragments are not sent to servers, so server redirects cannot preserve them. |
| `notes` | Maintainer context and constraints. |
When a legacy route is added, update the manifest and add or update one route module. Avoid duplicating redirect tables across pages.
#### Compatibility Matrix
| Representative old URL | Preview behavior | Production behavior | Notes |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------- |
| `https://micronaut.io/core/` | Deferred until `/core/` routing is resumed | Deferred until main-host Core routing is resumed | Tracked here as a known legacy URL, but not implemented in this pass. |
| `/core/?q=bean` | Deferred until `/core/` routing is resumed | Deferred until main-host Core routing is resumed | Query/hash preservation should be covered when this route is reintroduced. |
| `https://docs.micronaut.io/latest/guide/` | `/micronaut-web/latest/guide/` redirects to `/micronaut-web/docs/core/` | Redirects to Core docs on the newest published line | Every `/latest/` page redirects onto the line it mirrors. |
| `https://docs.micronaut.io/latest/guide/index.html#ioc` | `/micronaut-web/latest/guide/index.html` redirects to `/micronaut-web/docs/core/#ioc` in client-capable redirects | Redirects to Core docs on the newest line, same section | Fragments require client redirect pages. |
| `https://guides.micronaut.io/latest/index.html` | `/micronaut-web/latest/index.html` redirects to `/micronaut-web/guides/` | Redirects to `https://guides.micronaut.io/` | Query strings are preserved. |
| `https://guides.micronaut.io/latest/tag-security.html` | Redirects to the generated `/guides/` tag route when present, otherwise external production tag URL | Redirects to the root-level guide tag | Existing tag compatibility stays generated from guide metadata. |
| `https://guides.micronaut.io/latest/micronaut-http-client.html` | Redirects to slash-style generated `/guides/` overview when present, otherwise external production URL | Redirects to the root-level guide overview | Applies to guide overview `.html` pages. |
| `https://guides.micronaut.io/latest/micronaut-http-client-gradle-java.html` | Redirects to slash-style generated `/guides/` variant when present, otherwise external production URL | Redirects to the root-level guide variant | Applies to language/build variants. |
| `https://guides.micronaut.io/latest/micronaut-http-client-gradle-java.zip` | Redirects to production ZIP URL | ZIP remains downloadable at the root | ZIP redirects are temporary external redirects. |
| `https://micronaut.io/blog/2020-04-30-introducing-micronaut-launch.html` | Redirects to the canonical dated post | Redirects to the canonical dated post | Dated blog aliases are generated from post metadata. |
| `https://micronaut.io/blog/2019-07-18-unleashing-predator-precomputed-data-repositories.html` | Redirects to `/2019/07/18/announcing-micronaut-data/` | Same canonical post | Explicit historical aliases remain in `blog-redirects`. |
| Any supported route with `#section` | Same-document anchors stay intact; client redirect pages preserve hashes across route changes | Same rule | Server redirects cannot see fragments. |
#### Canonical URL Rules
- Main-site canonical content uses `https://micronaut.io/`.
- Docs canonical catalog pages use `https://docs.micronaut.io/`; Core legacy docs paths continue to resolve.
- Guides canonical generated guide URLs use `https://guides.micronaut.io/`; `/latest/` is retained only for redirects.
- GitHub Pages preview URLs must always be generated with `ASTRO_BASE`, not hard-coded as production links.
- Split GitHub Pages deployments must use the repo-name bases until custom domains are enabled: `/micronaut-web/`, `/micronaut-docs-v2/`, and `/micronaut-guides-v2/`.
- Docs version publishing updates the selector from the Pages branch and preserves shared root assets so older versions do not duplicate the same asset trees.
- Legacy URLs should prefer permanent redirects unless the destination points to another production host for generated artifacts, where temporary redirects are safer.
- Main-host `/core/` compatibility is intentionally deferred for now; add it through `src/lib/route-compatibility.ts` when route work resumes.
- `src/layouts/WebLayout.astro` is the single place social and structured-data tags are emitted. Open Graph, Twitter card, and JSON-LD values come from the `title` and `description` props, so a page that wants a useful share card passes a real description; blog posts and guides also pass `pageType="article"` and `publishedTime`. The share image is served from the main site for every surface.
#### Accessibility And Performance Acceptance Criteria
- Docs accessibility target: 100 after generated docs are present.
- No known shared unnamed logo link or generated heading-anchor link remains.
- Repeated generic links must have accessible names that identify the target item.
- CLS remains `0` for docs mobile.
- Docs mobile performance improves from the baseline without introducing new render-blocking script work.
- Images in static components have explicit intrinsic dimensions or a stable sizing wrapper.
- Generated docs images receive lazy loading, async decoding, and dimensions when the browser can determine them.
#### Manual QA Checklist
- Build with `ASTRO_BASE=/micronaut-web/` and verify all preview links keep the base path.
- Check `/`, `/docs/`, `/docs/core/`, `/latest/index.html`, `/latest/guide/`, `/latest/guide/index.html`, `/guides/`, a guide detail page, `/blog/`, a dated blog alias, and a content page.
- Repeat the checks on desktop and mobile widths.
- Verify `/latest/guide/index.html#ioc` preserves the fragment after redirect.
- Verify guides filters update and restore state with `q`, `category`, `tag`, and `sort`.
- Re-run PageSpeed or Lighthouse-style checks for homepage, docs index, and Core docs after deployment assets are available.
#### Automated Checks
Run:
```bash
npm run typecheck
npm run typecheck:scripts
npm run test:main-site
npm run test:asciidoc
npm run test:guides
npm run test:docs
npm run build
```
This repository keeps shared Asciidoc renderer coverage in `test:asciidoc` and docs integration coverage in `test:docs`; use `test:docs` for planned `test:platform-docs` coverage unless a separate script is introduced.
## Astro Publishing Best Practices
Keep published content canonical. A content page should have one source route, and compatibility URLs such as legacy blog paths should redirect to that route instead of rendering duplicate page bodies. When adding a compatibility route, prefer the centralized redirect and alias helpers so redirects remain `noindex` and easy to audit.
Route internal links through `src/lib/base-path.ts` or `src/lib/deployment-config.ts`. Do not hard-code `/docs`, `/guides`, `/latest`, or GitHub Pages repository prefixes in components or generated HTML; the deployment helpers keep links valid across all-in-one preview, standalone docs, standalone guides, and the main site.
Use Astro islands deliberately. Hydrate only UI that must run in the browser, and prefer static Astro markup for shared layout such as headers, navigation structure, and content shells wherever possible. Reserve `client:load` for controls that must be interactive immediately; use `client:idle` or `client:visible` for lower-priority UI.
#### Island Usage
Default to static Astro components for route chrome and generated content. Generated docs, generated guides, sidebar link trees, version lists, and article bodies should render as HTML first and should not become React islands just to attach a small behavior.
Use a React island only when the component owns meaningful client state, keyboard handling, focus management, or third-party interactive primitives. Current docs pages intentionally hydrate `SiteHeader`, `DocsSidebarRailControl`, and `DocsSidebarMobileSheet`. The guides catalog renders each card from `src/components/web/latest-guide-card.astro` and hydrates only `GuideVariantMenu`, and only for guides that offer more than one variant. Docs scroll-spy behavior lives in `src/components/web/docs-scroll-spy.astro` as a processed Astro script. Do not reintroduce a docs version switcher island; `src/components/web/docs-version-selector.astro` renders fallback options statically and uses a processed Astro script to fetch `/versions.json`.
For small native controls, use an Astro component plus a processed `<script>` instead of `client:*`. The script should import shared routing helpers, leave server-rendered fallback markup usable when fetches fail, and enhance all matching instances on the page. If the control can appear inside a hydrated React island, such as content passed into a mobile sheet, use delegated events and handle late DOM insertion through `astro:hydrate` or a narrowly scoped observer.
When adding, removing, or changing an island, inspect built HTML for `<astro-island>` markers and update tests that encode the expected island inventory. A docs page should not include `DocsVersionSwitcher` in `component-export`, `component-url`, or bundled source output.
Run generated-content processing at build time. Syntax highlighting, Asciidoctor rendering, properties/YAML/TOML/config conversion, and generated-content transformations must not ship to the browser runtime. Do not include `shiki`, `@shikijs/*`, `asciidoctor`, `@asciidoctor/*`, or config conversion/parsing libraries in public client bundles.
Use `is:inline` only for intentional critical scripts, such as the early theme script that prevents a visible color-mode flash. Non-critical scripts should be processed by Astro so they can be bundled, deduplicated, and cached.
To open any Astro-rendered page with a chosen color mode, add `?theme=dark` or `?theme=light` to its URL. The preset overrides the saved mode and becomes the saved preference for subsequent navigation.
Keep shared CSS focused. Global design tokens and cross-surface primitives belong in `src/styles/globals.css`, but route-specific styling should stay close to the route or component that needs it. Avoid adding one-off page styles to the global baseline.
Deduplicate public assets before publishing. Prefer canonical asset paths for shared logos, brand files, PDFs, and generated content assets, and keep legacy copies only when external compatibility requires them.
Prune published artifacts. Surface publication should remove unreferenced `_astro` chunks and unrelated surface output so Pages branches do not accumulate stale JavaScript, CSS, docs, guides, or template artifacts.
Pin npm dependencies. Avoid `latest` ranges in `package.json`; use exact or caret-bounded versions so local builds, CI, and Pages publishes resolve the same Astro, React, Vite, and tooling behavior.