. . . . . . . .
| | | | | | | |
| | | |\ /| | | |
| | | | \____ ____/ | | | |
| | | | \_____________________/ | | | |
| | | | | | | | | | | | |
______|_|_|_|______|____|____|____|____|______|_|_|_|______
================================================================
Markdown task files that people can edit, agents can update, and apps can import without taking ownership of the data.
Use Embridge when a list needs to stay readable as plain Markdown and still survive machine parsing, stable IDs, metadata, sync, and round trips through different tools.
You want the file to remain comfortable for humans, but you also need agents and apps to know what changed, which item is which, and how to preserve unknown fields.
.md file.A coding agent can add, complete, split, or annotate tasks while preserving stable item IDs and human-written context.
Keep project work in files that are easy to diff, review, branch, merge, and archive without asking a database for permission.
Give a GUI a predictable Markdown shape instead of inventing a private schema that only one tool understands.
Use Markdown lists for the human layer, then add due dates, status, tags, comments, attachments, and document metadata as needed.
Embridge is Markdown with just enough structure: forgiving while you type, deterministic when a parser imports it.
- apples
- pears
- orangesA plain list is valid enough for capture, notes, and low-ceremony tasks.
# To-do
- [ ] Fix login timeout bug
"repro in auth flow", prio: high, due: 2025-01-20, id: abc123d
# Done
- [x] Set up CI pipeline
id: ghi789aIDs, metadata, comments, sections, and document hints appear when apps and agents need reliable references.
key: value pairs like prio: high, due: 2025-01-20, id: abc123d.id fields enable reliable automation, syncing, and merge conflict resolution.Write tasks in a normal Markdown file from any editor.
The agent changes the intended item and keeps context intact.
A GUI reads sections, status, due dates, tags, and comments.
The .md file remains the source of truth.
# Sprint
- [ ] Add password timeout warning
prio: high, due: 2025-01-20, id: auth7kd
> @agent: found failing path in session renewal
- [x] Set up CI pipeline
id: ci92mqa# Sprint
- [ ] Add password timeout warning {auth7kd} - 2 fields, 1 comment
- [x] Set up CI pipeline {ci92mqa}That is the core bridge: human-readable text on one side, parser-readable structure on the other, with the file staying in the middle.
Paste or edit Embridge Markdown. The browser-side validator checks structure, reports warnings, and shows the parse outline it inferred. No server receives the file.
[]
Use the v0.1.1 reference for syntax, metadata, comments, blank-lines mode, and sync-ready expectations.
SpecificationCompare minimal lists, full sync-ready output, document metadata, attachments, and edge cases.
Example outputThe repository includes a JavaScript reference parser and conformance fixtures for expected parse behavior.
Reference parserApps should keep UI-only state outside the file and preserve unknown fields for forward compatibility.
Conformance testsExcellent for human capture, but weak conventions for stable IDs, metadata, comments, and app round trips.
Portable and proven, but flat and symbol-heavy. Embridge stays sectioned, nested, and Markdown-native.
Easy for machines, less comfortable for daily task editing. Embridge keeps the human layer first.
Useful interfaces, but the app often owns the model. Embridge lets many tools share one plain file.
Name it for the list: todo.md, shopping.md, packing.md, project.md, or anything else that belongs in plain text.
Use checkboxes, metadata lines, IDs, comments, and sections when tooling needs them.
Use the validator, fixtures, and reference parser before trusting an import/export workflow.