Arg0/Docs

Bridge MD

Interactive documents with executable components - Define API endpoints, authentication, and workflows in markdown with powerful interactive and executable components.

Bridge MD is a markdown-based format for defining interactive documents with executable components.

Overview

Bridge MD extends standard markdown with special annotations for defining:

  • API endpoints
  • Authentication methods
  • Executable actions
  • Workflow definitions
  • Interactive components

Basic Syntax

@auth - Authentication

Define how to authenticate with external services:

yaml
## @auth SlackOAuth
type: oauth2
service: slack
scope: chat:write,channels:read

@endpoint - API Endpoint

Document API endpoints with full specifications:

yaml
## @endpoint SlackSendMessage
method: POST
url: https://slack.com/api/chat.postMessage
auth: SlackOAuth
body:
  channel: string
  text: string

@action - Executable Action

Map natural language to API calls:

yaml
## @action SendSlackNotification
triggers:
  - "Slack notification"
  - "Send to {{channel}}"
endpoint: SlackSendMessage
input:
  channel: "{extract:channel}"
  text: "{prompt}"

@workflow - Workflow Definition

Define AI-powered workflows:

markdown
=== Workflow: expense-approval ===

Automated expense approval workflow

**Triggers**: GitHub webhook (issues.opened)
**Context**: approval_channel=#general

**Workflow**:

**Step 1**: Receive expense
- [ ] Receive expense report @endpoint ReceiveReport
  Input:
    - source={extract:source}
  Output:
    - report_id

Interactive Components

@actions

Track and manage tasks:

markdown
## @actions

- [-] Implement JWT auth
- [ ] Add avatar upload
- [~] Review code

Status indicators:

  • - [ ] - Pending
  • - [-] - In progress
  • - [x] - Completed
  • - [~] - In review

@ai_activity

Track AI changes to components:

markdown
## @ai_activity

AI modified the authentication flow at 2024-01-15 10:30

@ai_delegation

Delegate tasks to AI with progress tracking:

markdown
## @ai_delegation

Task: Implement user registration
Status: In progress
ETA: 2 hours

Execution Flow

  1. Parse - Extract @auth, @endpoint, @action definitions
  2. Match - Match user prompt to action triggers
  3. Extract - Extract variables from prompt
  4. Resolve Auth - Get token from service_integrations
  5. Execute - Call API with resolved auth
  6. Return - Return result to user

Document Structure

Frontmatter

yaml
---
title: "API Bridge"
version: "1.0"
---

Sections

Organize content into logical sections:

markdown
# User Management API

## System Overview

### Frontend
- Next.js 15 + TypeScript
- Path: ./apps/web

### Backend
- Service: user-api
- Path: ./services/user-api

Integration with Arg0 Desktop

Bridge MD Page

The Bridge MD Page in Arg0 Desktop provides:

  • Editor: Markdown editor with syntax highlighting
  • Preview: Live preview of interactive components
  • Execution: Execute actions and workflows
  • Validation: Validate syntax and structure

Inline Editing

Edit documents directly in preview mode:

  1. Open Bridge MD document
  2. Switch to preview mode
  3. Click on text to edit
  4. Changes save automatically

Slash Commands

Insert blocks using slash commands:

  1. Type / in editor
  2. Select block type
  3. Configure block parameters
  4. Insert into document

Best Practices

Document Organization

  • Use clear, descriptive titles
  • Organize into logical sections
  • Include examples for each endpoint
  • Document authentication requirements
  • Provide error handling guidance

Action Definition

  • Use natural language triggers
  • Include multiple trigger variations
  • Map to appropriate endpoints
  • Validate input parameters
  • Handle errors gracefully

Workflow Design

  • Keep workflows focused
  • Use clear step names
  • Define explicit input/output
  • Include checkpoints for critical steps
  • Test workflows before production

Examples

Simple API Document

markdown
---
title: "User API"
version: "1.0"
---

# User Management API

## @auth UserAuth
type: bearer
service: user-api

## @endpoint CreateUser
method: POST
url: https://api.example.com/users
auth: UserAuth
body:
  name: string
  email: string

## @action Create User
triggers:
  - "Create user"
  - "Add user"
endpoint: CreateUser
input:
  name: "{extract:name}"
  email: "{extract:email}"

Workflow Document

markdown
=== Workflow: user-onboarding ===

New user onboarding workflow

**Triggers**: Webhook (user.created)
**Context**: welcome_email=true

**Workflow**:

**Step 1**: Send welcome email
- [ ] Send welcome email @endpoint SendEmail
  Input:
    - email={extract:email}
    - template=welcome
  Output:
    - email_id

**Step 2**: Create user profile
- [ ] Create profile @endpoint CreateProfile
  Input:
    - user_id={extract:user_id}
  Output:
    - profile_id