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:
## @auth SlackOAuth
type: oauth2
service: slack
scope: chat:write,channels:read
@endpoint - API Endpoint
Document API endpoints with full specifications:
## @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:
## @action SendSlackNotification
triggers:
- "Slack notification"
- "Send to {{channel}}"
endpoint: SlackSendMessage
input:
channel: "{extract:channel}"
text: "{prompt}"
@workflow - Workflow Definition
Define AI-powered workflows:
=== 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:
## @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:
## @ai_activity
AI modified the authentication flow at 2024-01-15 10:30
@ai_delegation
Delegate tasks to AI with progress tracking:
## @ai_delegation
Task: Implement user registration
Status: In progress
ETA: 2 hours
Execution Flow
- Parse - Extract @auth, @endpoint, @action definitions
- Match - Match user prompt to action triggers
- Extract - Extract variables from prompt
- Resolve Auth - Get token from service_integrations
- Execute - Call API with resolved auth
- Return - Return result to user
Document Structure
Frontmatter
---
title: "API Bridge"
version: "1.0"
---
Sections
Organize content into logical sections:
# 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:
- Open Bridge MD document
- Switch to preview mode
- Click on text to edit
- Changes save automatically
Slash Commands
Insert blocks using slash commands:
- Type
/in editor - Select block type
- Configure block parameters
- 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
---
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
=== 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
Related Documentation
- Workflows - Workflow automation
- Agent Implementation - Agent system
- Docs & Plan - Document management