Merge branch 'main' into feature/langgraph-restaurant-finder

Author: faizan842

.geminiignore

@@ -0,0 +1,4 @@
+# Ignore large lock files that aren't useful for context
+**/pnpm-lock.yaml
+**/package-lock.json
+**/uv.lock

.github/workflows/docs.yml

@@ -69,6 +69,12 @@ jobs:
       - name: Install documentation dependencies
         run: pip install -r requirements-docs.txt
 
+      - name: Validate documentation conversion script
+        run: pip install pytest && pytest docs/scripts/test_convert_docs.py
+
+      - name: Convert Admonitions in Documentation
+        run: python docs/scripts/convert_docs.py --mode github-to-mkdocs
+
       - name: Build Documentation (PR Check)
         if: github.event_name == 'pull_request'
         run: mkdocs build

README.md

@@ -9,7 +9,7 @@ to generate or populate rich user interfaces.
 
 *A gallery of A2UI rendered cards, showing a variety of UI compositions that A2UI can achieve.*
 
-## ⚠️ Status: Early Stage Public Preview
+## ⚠️ Status: Early stage public preview
 
 > **Note:** A2UI is currently in **v0.8 (Public Preview)**. The specification and
 implementations are functional but are still evolving. We are opening the project to
@@ -30,7 +30,7 @@ component library (Flutter, Angular, Lit, etc.).
 This approach ensures that agent-generated UIs are
 **safe like data, but expressive like code**.
 
-## High-Level Philosophy
+## High-level philosophy
 
 A2UI was designed to address the specific challenges of interoperable,
 cross-platform, generative or template-based UI responses from agents.
@@ -63,7 +63,7 @@ places security firmly in the developer's hands, enabling them to enforce
 strict sandboxing policies and "trust ladders" directly within their custom
 component logic rather than relying solely on the core system.
 
-## Use Cases
+## Use cases
 
 Some of the use cases include:
 
@@ -98,7 +98,7 @@ A2UI is designed to be a lightweight format, but it fits into a larger ecosystem
 * **Host Frameworks:** Requires a host application built in a supported framework
 (currently: Web or Flutter).
 
-## Getting Started
+## Getting started
 
 The best way to understand A2UI is to run the samples.
 
@@ -108,7 +108,7 @@ The best way to understand A2UI is to run the samples.
 * Python (for agent samples)
 * A valid [Gemini API Key](https://aistudio.google.com/) is required for the samples.
 
-### Running the Restaurant Finder Demo
+### Running the Restaurant Finder demo
 
 1. **Clone the repository:**
 
@@ -117,7 +117,7 @@ The best way to understand A2UI is to run the samples.
     cd A2UI
     ```
 
-2. **Set your API Key:**
+2. **Set your API key:**
 
     ```bash
     export GEMINI_API_KEY="your_gemini_api_key"
@@ -160,10 +160,10 @@ to try out as well.
 
 We hope to work with the community on the following:
 
-* **Spec Stabilization:** Moving towards a v1.0 specification.
-* **More Renderers:** Adding official support for React, Jetpack Compose, iOS (SwiftUI), and more.
-* **Additional Transports:** Support for REST and more.
-* **Additional Agent Frameworks:** Genkit, LangGraph, and more.
+* **Spec stabilization:** Moving towards a v1.0 specification.
+* **More renderers:** Adding official support for React, Jetpack Compose, iOS (SwiftUI), and more.
+* **Additional transports:** Support for REST and more.
+* **Additional Agent frameworks:** Genkit, LangGraph, and more.
 
 ## Contribute
 

a2a_agents/python/a2ui_agent/README.md

@@ -1,16 +1,16 @@
-# A2UI Agent Implementation
+# A2UI Agent implementation
 
 The `a2a_agents/python/a2ui_agent/` is the Python implementation of the a2ui agent library.
 
-### Extension Components (`src/a2ui/extension`)
+### Extension components (`src/a2ui/extension`)
 
 The `src/a2ui/extension` directory contains the core logic for the A2UI agent extension:
 
 *   **`a2ui_extension.py`**: Core utilities for extension management and A2UI part handling.
 *   **`a2ui_schema_utils.py`**: Schema manipulation helpers.
 *   **`send_a2ui_to_client_toolset.py`**: An example implementation of using ADK toolcalls to implement A2UI.
 
-## Running Tests
+## Running tests
 
 1. Navigate to the a2ui_agent dir:
 
@@ -40,4 +40,4 @@ All operational data received from an external agent—including its AgentCard,
 
 Similarly, any UI definition or data stream received must be treated as untrusted. Malicious agents could attempt to spoof legitimate interfaces to deceive users (phishing), inject malicious scripts via property values (XSS), or generate excessive layout complexity to degrade client performance (DoS). If your application supports optional embedded content (such as iframes or web views), additional care must be taken to prevent exposure to malicious external sites.
 
-Developer Responsibility: Failure to properly validate data and strictly sandbox rendered content can introduce severe vulnerabilities. Developers are responsible for implementing appropriate security measures—such as input sanitization, Content Security Policies (CSP), strict isolation for optional embedded content, and secure credential handling—to protect their systems and users.
+Developer Responsibility: Failure to properly validate data and strictly sandbox rendered content can introduce severe vulnerabilities. Developers are responsible for implementing appropriate security measures—such as input sanitization, Content Security Policies (CSP), strict isolation for optional embedded content, and secure credential handling—to protect their systems and users.

a2a_agents/python/a2ui_agent/src/a2ui/extension/a2ui_extension.py

@@ -29,7 +29,9 @@
 SUPPORTED_CATALOG_IDS_KEY = "supportedCatalogIds"
 INLINE_CATALOGS_KEY = "inlineCatalogs"
 
-STANDARD_CATALOG_ID = "https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json"
+STANDARD_CATALOG_ID = (
+    "https://a2ui.org/specification/v0_8/standard_catalog_definition.json"
+)
 
 
 def create_a2ui_part(a2ui_data: dict[str, Any]) -> Part:

docs/community.md

@@ -8,8 +8,9 @@ A2UI is an open-source project licensed under Apache 2.0. We welcome contributio
 
 ## Community Showcase
 
-!!! info "Coming soon..."
-    We are considering how best to showcase community projects, examples, themes, renderers, custom components, and more.  A 4 minute (or less) demo video and code sample linked in Github discussions is a great way to show off your work.
+> ℹ️ **Coming soon...**
+>
+> We are considering how best to showcase community projects, examples, themes, renderers, custom components, and more.  A 4 minute (or less) demo video and code sample linked in Github discussions is a great way to show off your work.
 
 ## Project Partners
 

docs/guides/agent-development.md

@@ -94,8 +94,9 @@ Select `my_agent` from the list, and ask questions about restaurants in New York
 
 Getting the LLM to generate A2UI messages requires some prompt engineering.  
 
-!!! warning "Attention"
-    This is an area we are still designing.  The developer ergonomics of this are not yet finalized.
+> ⚠️ **Attention**
+>
+> This is an area we are still designing.  The developer ergonomics of this are not yet finalized.
 
 For now, let's copy the `a2ui_schema.py` from the contact lookup example.  This is the easiest way to get the A2UI schema and examples for your agent (subject to change).
 

docs/guides/client-setup.md

@@ -15,9 +15,10 @@ Integrate A2UI into your application using the renderer for your platform.
 
 ## Web Components (Lit)
 
-!!! warning "Attention"
-    The Lit client library is not yet published to NPM. Check back in the
-    coming days.
+> ⚠️ **Attention**
+>
+> The Lit client library is not yet published to NPM. Check back in the
+> coming days.
 
 ```bash
 npm install @a2ui/web-lib lit @lit-labs/signals
@@ -35,9 +36,10 @@ TODO: Add verified setup example.
 
 ## Angular
 
-!!! warning "Attention"
-    The Angular client library is not yet published to NPM. Check back in the
-    coming days.
+> ⚠️ **Attention**
+>
+> The Angular client library is not yet published to NPM. Check back in the
+> coming days.
 
 ```bash
 npm install @a2ui/angular @a2ui/web-lib

docs/index.md

@@ -20,11 +20,12 @@ A2UI enables AI agents to generate rich, interactive user interfaces that render
 
 </div>
 
-!!! warning "️Status: Early Stage Public Preview"
-    A2UI is currently in **v0.8 (Public Preview)**. The specification and
-    implementations are functional but are still evolving. We are opening the project to
-    foster collaboration, gather feedback, and solicit contributions (e.g., on client renderers).
-    Expect changes.
+> ⚠️ **️Status: Early Stage Public Preview**
+>
+> A2UI is currently in **v0.8 (Public Preview)**. The specification and
+> implementations are functional but are still evolving. We are opening the project to
+> foster collaboration, gather feedback, and solicit contributions (e.g., on client renderers).
+> Expect changes.
 
 ## At a Glance
 

docs/introduction/agent-ui-ecosystem.md

@@ -6,8 +6,9 @@ The space for agentic UI is evolving rapidly, with excellent tools emerging to s
 
 The A2UI approach is to send JSON as a message to the client, which then uses a renderer to convert it into native UI components.  LLMs can generate the component layout on the fly or you can use a template.
 
-!!! tip ""
-    **This makes it secure like data, and expressive like code.**
+> 💡
+>
+> **This makes it secure like data, and expressive like code.**
 
 This rest of this page will help you understand A2UI in relationship to other options.