adev — angular.dev

The documentation site at angular.dev. An Angular SSG application that lives at adev/. Documentation content is authored in Markdown under adev/src/content/; API reference is generated from TypeScript source by adev/shared-docs/pipeline/api-gen.

Purpose

adev is angular.dev. It serves:

• The "Tutorial," "Essentials," "Guides," "API," and "Tools" sections.
• The interactive playground tutorials (powered by the same Angular runtime built from this repo).
• The "Update guide" tool that walks users through major upgrades.
• The "Reference" section auto-generated from @angular/* source.

The site is rebuilt and deployed on every merge to main (and on protected release branches) through the adev-preview-build.yml and adev-preview-deploy.yml GitHub Actions.

Directory layout

adev/
├── src/
│   ├── app/             # Angular components (page shells, navigation)
│   ├── assets/          # Images, illustrations, OpenGraph artwork
│   ├── content/         # Markdown for guides, tutorials, API stubs
│   ├── styles/          # Global SCSS
│   ├── context/         # Build-time configuration injected into pages
│   ├── llms.txt         # AI-crawler instructions (recently added)
│   └── main.ts / main.server.ts
├── shared-docs/         # Reusable doc components and the API-gen pipeline
│   ├── pipeline/
│   │   └── api-gen/     # TypeScript → JSON manifest extraction
│   └── ...
├── scripts/             # Site build helpers
├── firebase.json        # Hosting deployment config
└── tsconfig.*.json

The shared-docs/ workspace is intentionally separate from src/ because it is reused by the angular.io archive and other doc sites within the org.

How content is built

graph LR
  Markdown["adev/src/content/*.md"] --> MDPipeline["adev/shared-docs/pipeline<br/>(markdown → HTML)"]
  TSSource["packages/*/src/**.ts"] --> APIGen["api-gen<br/>(TypeScript → JSON manifest)"]
  APIGen --> APIPages["Generated API pages"]
  MDPipeline --> Site["Angular SSG site<br/>(adev/src/app)"]
  APIPages --> Site
  Site --> Build["bazel //adev:build"]
  Build --> Static["adev/dist (static + SSR shell)"]
  Static --> Firebase

API reference content is therefore an artifact of the framework code itself; editing a JSDoc on a public API in packages/*/src/ is what changes the angular.dev API page.

Authoring docs

The repo enforces a documentation style guide. The companion skill is adev-writing-guide (use it via the Skill tool when editing adev/). It covers:

• Google Technical Writing standards.
• Angular-specific markdown extensions: callout components, tabs, embedded code samples.
• Code-block conventions and the embedded playground.

Markdown changes go through normal review. Content under adev/src/content/ is committed with a docs: commit type; infrastructure changes inside adev/ use docs-infra: (per the commit-message guide).

Local development

pnpm adev          # ibazel-watched dev server on http://localhost:4200
pnpm adev:build    # Single full build into adev/dist/

Deployment

CI runs three workflows for documentation:

• adev-preview-build.yml — build the site for a PR.
• adev-preview-deploy.yml — deploy the PR build to a preview URL.
• cross-repo-adev-docs.yml — trigger downstream rebuilds when shared docs change in sister repos.

Production deploy goes to Firebase Hosting (config in adev/firebase.json).

Integration points

• packages/ — the API reference pages depend on JSDoc in framework source. When making a public API change, run pnpm public-api:update and verify the rendered page in pnpm adev.
• Tutorials and the playground — the playground embeds a live Angular runtime built from the same repo. Breaking changes in core or the compiler must be reflected in tutorial content.
• @angular/build — the build glue that produces the SSG output. Lives in the angular-cli repo; consumed via the workspace package.json.

Entry points for modification

• A new doc page: add a Markdown file under adev/src/content/, register it in the navigation tree (configured in adev/src/app/), submit with docs: commit type.
• A new doc component (e.g., a callout, an embeddable widget): add it to adev/shared-docs/ so other doc sites can reuse it. Use docs-infra: commit type.
• A change to API extraction: edit adev/shared-docs/pipeline/api-gen/.