docs(a2ui): Update documentation to align with v0.9 specification by gspencergoog · Pull Request #622 · google/A2UI

gspencergoog · 2026-02-12T01:22:07Z

Description

This updates the docs folder to describe the 0.9 specification instead of 0.8. I added disclaimers that the renderers are not yet up to spec, but I think it's still a little odd to have docs for 0.9 and no examples yet.

Better that the docs represent the current spec, though.

zeroasterisk

The content updates look accurate, but I think we need version-specific documentation tabs before merging this.

⚠️ Blocking concern

Users on 0.8 renderers visiting the docs will see 0.9 examples that don't work for them. We should add a version switcher (like React/Vue docs have) so users can select their renderer version and see matching examples.

Options:

Add version tabs to the docs site (preferred) — see React docs or Vue docs
Maintain separate /v0.8/ and /v0.9/ doc paths
At minimum, add prominent "Version: 0.9" badges and link to archived 0.8 docs

Happy to help spec this out if useful. What do you think?

gspencergoog · 2026-02-13T22:11:58Z

The content updates look accurate, but I think we need version-specific documentation tabs before merging this.

Yeah, I wondered about this too. As for what form this should take, the examples you gave basically just have a banner or a link to the previous versions.

React:

Vue:

And they start off on the "current" version by default.

That's sort of what I was going for here anyhow: the 0.8 spec docs are still there, but they're pared down.

What if we just do what React does and just keep previous versions as separate sites? I mean, for now, we can just have them at a different URL with the version in it, so we don't need separate host names, but does that sound good?

And the bigger question is: do we start people on the 0.9 docs or the 0.8 docs when they go to a21ui.org?

gspencergoog · 2026-02-13T23:01:49Z

I assume we don't want to go as far as Python does: https://docs.python.org/3/

It has a pulldown to select the version to view. I think only A2UI renderer implementers will be interested in that level of detail, and they can still browse the docs if they are at a separate URL like https://a2ui.org/0.8/quickstart/

So, I'm going to proceed like this: I'll convert this PR so that everything except for the Intro and FAQ tabs are under a version number, and the landing page will explain the different versions and their current state. The stuff under 0.8 will be the original content from 0.8 and the 0.9 content will be this content. The Intro and FAQ tabs will be 0.9 specific in the places where an example is given, and I'll a FAQ about the versions.

Sound good @zeroasterisk ?

gspencergoog · 2026-02-17T21:50:59Z

Okay, I think this reflects what you were asking for.

PTAL @zeroasterisk

- Replaced legacy v0.8 terminology (e.g., `beginRendering` -> `createSurface`, `usageHint` -> `variant`). - Updated schema examples for components and messages throughout the documentation. - Migrated legacy documentation to `docs/v0_8/` archive. - Updated guides and concepts to reflect v0.9 changes. - Add 'fit' and 'variant' properties to Image component documentation. - Clarify 'updateDataModel' value optionality (omission implies deletion). - Add new 'Client-Side Functions' reference page and link it. - Mention client-side formatting in best practices.

- Move v0.8 documentation to `docs/specification/`. - Add wrapper files for v0.8, v0.9, v0.10 specifications, evolution guides, and extension specs. - Update mkdocs.yaml to reflect new structure and include all relevant documents. - Update prepare_docs.py to handle file copying, JSON flattening, and comprehensive link rewriting for all versions. - Fix internal links in markdown files to point to correct relative paths. - Remove deprecated `docs/v0_8` directory.

docs: add mkdocs-redirects to requirements Fixes CI build error by adding missing dependency `mkdocs-redirects`, which is used in `mkdocs.yaml` for URL redirection.

jacobsimionato · 2026-02-20T10:35:07Z

docs/v0.10/specification/docs/a2ui_custom_functions.md

Do we need any docs for v0.10 at this stage? I think it would be nicer to not maintain them if necessary at this point.
I propose rm -r docs/v0.10

Though I guess the script just copied these, so maybe it's more work to not have them copied. If you feel the minimum maintenance option is to just check these in, I'm fine with that!

jacobsimionato · 2026-02-20T10:39:15Z

docs/scripts/prepare_docs.py

+Prepares the raw A2UI specification files for use in the MkDocs build.
+
+This script performs the following tasks:
+1.  **Copies Source Files**: Copies the raw specification files from the root `specification/` directory (e.g., `specification/v0_9`) into the versioned documentation structure (e.g., `docs/v0.9/specification`).


Would it make sense to .gitignore the copied files and have this be part of the build process, rather than checking in the copied files? That would keep the repo smaller and avoid confusion about what needs to be maintained etc.

Or is there some way to at least mark the copied files very clearly, e.g. by placing them in generated/ or script_output/ or something? I guess maybe that breaks all the links and/or makes the URLs weird?

No, we should just .gitignore them and not check them in. They're just copies, and we should only have one checked in.

zeroasterisk

I now doubt everything I said before :)

We need docs and specs in sync per version, but I think this is feeling kinda unwieldy to maintain.

Can we reduce scope some?
Can we reduce what needs multiple version of concurrent docs?

I appreciate you getting it to here, just feels like a lot

zeroasterisk · 2026-02-20T22:42:17Z

docs/v0.9/community.md

this just doesn't make sense... v0.9 community page?

Yeah, good point. We should move that up a level.

zeroasterisk · 2026-02-20T22:47:12Z

mkdocs.yaml

+      - FAQ: introduction/faq.md
+  - v0.9 (Current):
+      - Quickstart: v0.9/quickstart.md
+      - A2UI Composer ⭐: v0.9/composer.md


I think these items have to move out of versioned docs ^

zeroasterisk · 2026-02-20T22:47:45Z

mkdocs.yaml

+      - Catalogs: v0.9/catalogs.md
+      - Renderers (Clients): v0.9/renderers.md
+      - Transports (Message Passing): v0.9/transports.md
+      - Agents (Server-side): v0.9/agents.md


I agree all of the above are versioned docs ^

zeroasterisk · 2026-02-20T22:47:58Z

mkdocs.yaml

+      - Transports (Message Passing): v0.9/transports.md
+      - Agents (Server-side): v0.9/agents.md
+      - Community: v0.9/community.md
+      - Roadmap: v0.9/roadmap.md


not versioned

zeroasterisk · 2026-02-20T22:48:03Z

mkdocs.yaml

+      - Renderers (Clients): v0.9/renderers.md
+      - Transports (Message Passing): v0.9/transports.md
+      - Agents (Server-side): v0.9/agents.md
+      - Community: v0.9/community.md


not versioned

zeroasterisk · 2026-02-20T22:48:17Z

mkdocs.yaml

+      - Reference:
+          - Component Reference: v0.9/reference/components.md
+          - Message Reference: v0.9/reference/messages.md
+          - Client-Side Functions: v0.9/reference/functions.md


agree versioned

zeroasterisk · 2026-02-20T22:48:33Z

mkdocs.yaml

-      - Component Reference: reference/components.md
-      - Message Reference: reference/messages.md
+      - FAQ: introduction/faq.md
+  - v0.9 (Current):


not "current" until we have renderers ready

gspencergoog · 2026-02-20T23:06:31Z

I now doubt everything I said before :)

LOL! I do this on the daily.

We need docs and specs in sync per version, but I think this is feeling kinda unwieldy to maintain.

Can we reduce scope some?

Can we reduce what needs multiple version of concurrent docs?

I appreciate you getting it to here, just feels like a lot

It is a lot. :-)

I'm happy to keep iterating on this until we have something good, but would it be a good idea to hand this (or maybe the result of what we arrive at?) to someone with DevRel credentials?

Want me to keep iterating, or should I pause until we figure out some of the questions?

gspencergoog requested review from dmandar, jacobsimionato and zeroasterisk as code owners February 12, 2026 01:22

github-project-automation bot added this to A2UI Feb 12, 2026

github-project-automation bot moved this to Todo in A2UI Feb 12, 2026

gspencergoog force-pushed the update_docs branch from 409483c to 519a672 Compare February 12, 2026 01:24

google deleted a comment from google-cla bot Feb 12, 2026

google deleted a comment from gemini-code-assist bot Feb 12, 2026

gspencergoog enabled auto-merge (squash) February 12, 2026 03:28

zeroasterisk requested changes Feb 13, 2026

View reviewed changes

zeroasterisk mentioned this pull request Feb 13, 2026

Update the website documentation content #175

Closed

gspencergoog disabled auto-merge February 17, 2026 22:45

gspencergoog added 5 commits February 17, 2026 16:06

fixing links

2079869

Reorganize docs to keep 0.8 and 0.9 separate.

47aa1e6

docs: add mkdocs-redirects to requirements Fixes CI build error by adding missing dependency `mkdocs-redirects`, which is used in `mkdocs.yaml` for URL redirection.

docs: finalize v0.8/v0.9 catalogs.md and fix links

2a4b454

gspencergoog force-pushed the update_docs branch from d5f3dc1 to 2a4b454 Compare February 18, 2026 00:08

jacobsimionato reviewed Feb 20, 2026

View reviewed changes

Merge branch 'main' into update_docs

7d91d8a

zeroasterisk requested changes Feb 20, 2026

View reviewed changes

Comments

Conversation

gspencergoog commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

zeroasterisk left a comment

Choose a reason for hiding this comment

Uh oh!

gspencergoog commented Feb 13, 2026

Uh oh!

gspencergoog commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gspencergoog commented Feb 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zeroasterisk left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gspencergoog commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gspencergoog commented Feb 12, 2026 •

edited

Loading

gspencergoog commented Feb 13, 2026 •

edited

Loading

zeroasterisk left a comment •

edited

Loading