md2a2ui

README

md2a2ui

Go library that converts Markdown to A2UI component trees using goldmark.

Install

go get github.com/stump-wtf/md2a2ui

Usage

package main

import (
    "encoding/json"
    "fmt"
    
    "github.com/stump-wtf/md2a2ui"
)

func main() {
    md := `# Hello World

This is **bold** and *italic*.

- Item one
- Item two

| Column A | Column B |
|----------|----------|
| Cell 1   | Cell 2   |
`

    msg, err := md2a2ui.Convert(md)
    if err != nil {
        panic(err)
    }
    
    out, _ := json.MarshalIndent(msg, "", "  ")
    fmt.Println(string(out))
}

Markdown → A2UI Mapping

Markdown	A2UI Component
# H1–# H5	Text (variant: h1–h5)
###### H6	Text (variant: caption)
Paragraph	Text (variant: body)
Bullet/numbered list	List
Code block	Card wrapping Text
Blockquote	Card wrapping Text
--- (horizontal rule)	Divider
Image	Image
Table	Column of Row children
Inline bold/italic/code/links	Preserved as markdown in Text.text

License

MIT

Documentation

Overview

Package md2a2ui converts Markdown text into A2UI component trees.

It uses goldmark to parse CommonMark markdown and walks the resulting AST, emitting a flat list of A2UI components connected by ID references in the adjacency-list model the A2UI protocol expects.

The output is a complete updateComponents message, ready to marshal as JSON and send to any A2UI renderer that uses the v0.9 basic catalog.

Index

• Constants
• type Component
• type Message
  • func Convert(markdown string) (*Message, error)
  • func ConvertWithSurface(markdown, surfaceID string) (*Message, error)
  • func (m *Message) EnsureRootValid() error
  • func (m *Message) String() string
• type UpdateComponents

Constants

const Version = "v0.9"

Version is the A2UI protocol version this library targets.

Types

type Component

type Component struct {
	ID        string   `json:"id"`
	Component string   `json:"component"`
	Text      string   `json:"text,omitempty"`
	Variant   string   `json:"variant,omitempty"`
	Children  []string `json:"children,omitempty"`
	Child     string   `json:"child,omitempty"`
	Axis      string   `json:"axis,omitempty"`
	URL       string   `json:"url,omitempty"`
	AltText   string   `json:"altText,omitempty"`
	Direction string   `json:"direction,omitempty"`
}

Component is a single A2UI component in the adjacency-list model. Only the fields relevant to the markdown→A2UI mapping are included; the struct uses omitempty on optional fields so the JSON stays clean.

type Message

type Message struct {
	Version          string            `json:"version"`
	UpdateComponents *UpdateComponents `json:"updateComponents"`
}

Message is a top-level A2UI agent-to-renderer message containing an updateComponents payload. Marshal it to JSON and send it to a renderer that already has a surface created.

func Convert

func Convert(markdown string) (*Message, error)

Convert parses markdown and returns a complete updateComponents A2UI message. The component tree is rooted in a Column whose id is "root".

A custom surfaceId can be set via the ConvertWithSurface function.

func ConvertWithSurface

func ConvertWithSurface(markdown, surfaceID string) (*Message, error)

ConvertWithSurface is like Convert but lets the caller choose the surfaceId that appears in the updateComponents message.

func (*Message) EnsureRootValid

func (m *Message) EnsureRootValid() error

EnsureRootValid verifies that the component list has exactly one component with id "root". A2UI requires this.

func (*Message) String

func (m *Message) String() string

String returns a human-readable summary of the message for debugging.

type UpdateComponents

type UpdateComponents struct {
	SurfaceID  string      `json:"surfaceId"`
	Components []Component `json:"components"`
}

UpdateComponents is the A2UI message body that carries a flat list of component definitions for a specific surface.