GEML — a plain-text document format built to be edited in place, one section at…

GEML — General Expressive Markup Language

*English | 中文*

GEML is a lightweight markup language with uniform, addressable blocks and standard verbs.

Easy for humans to read, safe for agents to mutate. In agent-driven development and knowledge work, plain text and Markdown have no deterministic block boundaries: a program and a model trade the whole file in and the whole file back out — at best probing for it with line windows, and restating the original verbatim to rewrite it. Token cost grows with the length of the document, and the operation turns bloated. After a few rounds of rewriting, the copies excerpted elsewhere start to drift.

Contents: What it solves · What an LLM needs · What's different · The format in 1 minute · Profiles · Get hands-on · With an LLM · Maturity & versions · The design · Roadmap · Take part · License

You can start without changing a thing. geml list, geml find and geml get address the Markdown you already have — nothing is converted, no new files, your .md stays .md:

geml list    README.md                          # every section, as an address

geml get README.md '#key-features' # read ONE section, not the file geml set README.md '#key-features' --body # write one section back geml replace README.md 'old text' 'new text' # swap a string, told which block held it geml history save README.md -m 'tighten intro' # a revision into README.md.gemlhistory, beside the file

Only that section enters the agent’s context — a couple of KB, not the whole file, however long it grows. And every save is a revision you can read back or roll back, one block or the whole file.

▶ [Try it in the Playground](https://geml-spec.github.io/playground/) — no install, nothing to read first.

Need finer than a section — one block, one chart, one table? Let .geml stand in the middle ground: edit at that grain, and the --to md you ship never drifts from it.

A block has a name; the things inside it have a coordinate. A table's cell, a data block's leaf, a key in meta — each has a coordinate the structure already gives it, and get and set land on exactly that value.

geml get doc.geml '#fy[2]["Q1"]'                     # one cell

geml set doc.geml '#intake"fields"["name"]' # one leaf in the JSON

For people, it is plain text that reads clean; for agents, it is an addressable, verifiable, traceable, revertible ["Doc-as-a-Base"](https://geml-spec.github.io/manifesto).

---

GEML is minimal. It is plain text — still clean with no renderer in sight; one block syntax for the whole language; addressable, verifiable, referenceable structure, natively.

Instead of a separate mini-syntax for each kind of content, GEML carries every kind in one container: the typed block. Code is a block. So are tables, diagrams, math, callouts, even metadata — and a run of prose can be one too (=== text), whenever you want it addressable. Extending it later is just as plain. The shape is the same every time, which makes the language easy enough to learn that it's hard to get wrong.

Blocks have names so the verbs have somewhere to land — the full syntax is in the format in 1 minute.

What it solves

Problems solved

1. Context load and token bloat: JSON/XML carry heavy wrapper syntax, and Markdown lacks structural metadata and references; GEML reads and writes only the target block, so context cost stops growing with document length.
2. AST-level precision and parsing determinism: unstructured text degrades over rounds of LLM reads and writes — broken formatting, semantic drift; GEML's deterministic grammar maps to an AST, so programs and LLMs create, read, update and delete one block at a time.
3. Document copy fragmentation: multi-agent work and shared pipelines pass content around by copy-paste, leaving copies that drift apart; GEML is built around a single source of truth, with standard references and data binding in place of copies.

Key features

• AST-level structured operations: a document parses into a typed tree; an agent pinpoints its target and patches it in place, idempotently. Writes land as byte splices with whole-document re-validation, and every untouched byte stays as it was.
• Low-token reads and writes: what is saved is not markup characters but the part never read — #id hits one semantically complete block, and the rest never enters the context.
• Single source of truth, modular references: native cross-document, cross-fragment references; change the source once and every reference follows.
• Robust two-way reads and writes: one block shape for the whole language, easy to generate and hard to get wrong; a strict validator with precise error locations and repair feedback.
• Profile-based domain extensibility: declare a profile in === meta to add a domain vocabulary (design styles, forms, code graphs, media timelines) without new syntax; a declared vocabulary is checked by its own checker, with safe fallback to standard blocks in unknown environments.

---

What kind of text format does an LLM need?

Text in the AI era is "produced by models, read by people and models together".

Reading together means readability cannot be traded away; and when models settled on Markdown, it was a compromise made for want of anything better, not the final answer.

A text format built for people and models working together should change what reading and writing feel like for the machine:

• Fine-grained: address precisely by block, and by coordinate inside it — no more scanning the whole file;
• Structured: better organized, more flexible in what it holds;
• Consistent: one standard read/write interface, with other modalities extending it naturally;
• Zero barrier: minimal mental load, and a smooth, near-zero-cost migration.

Yet none of our existing text infrastructure was designed for this scene:

• Markdown (typeset for people): no stable structural blocks, no machine keys. To change one parameter, an agent must read and write the whole text — wasting context budget across multi-turn loops, and inviting drift in both format and meaning.
• JSON / XML (serialized for machines): full of wrapper syntax and structural noise — blocking natural human reading, while quietly eating expensive tokens in long contexts.
• Scratch memory and scattered files (no single source of truth): context is torn across chat history and Markdown copies everywhere; a copy is drift from the moment it is made, and version skew and hallucinated distortion follow.

The root of all three failures is each tool's own virtue: Markdown's "never error, write anything" is what gives people their freedom to write — and exactly why a machine cannot trust the structure it reads back; JSON/XML's strict schema is what gives machines their certainty — and exactly why nobody writes prose in it. The virtue is the defect, which is why patches cannot fix this: bolting "a broken reference must fail the build" onto Markdown betrays its contract, and stripping the wrapper syntax from JSON denies its nature. When people and agents start co-writing the same text at high frequency, what is needed is not a compromise between the two poles, but a format that treats "readable by people" and "operable by machines" as one design constraint from day one.

The answer: ["Doc-as-a-Base"](https://geml-spec.github.io/manifesto)

GEML is a new format, but the wine is old: enhancing and unifying Markdown-style expression, stripping away HTML-style presentational syntax, and the idea of fenced blocks come from Markdown, #ids and embeds from XML and AsciiDoc, inline projection from Obsidian, and the verbs from the [REST](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) architectural style of Dr. Roy Fielding's dissertation. What is new is one block container for all of them. It is a little like TypeScript to JavaScript — the syntax can't be compatible, but list, get, set, add and delete already work on the Markdown you have. That container gives plain-text documents one standard set of operational semantics:

A document no longer needs just a format — it needs a set of verbs. GEML keeps plain-text readability and adds deterministic block-level operations. The dilemma of engineering documents in the LLM era, and why these old practices belong in one new block container, is argued in full on the blog: "Why Do We Need a New Text Format in the Era of LLMs?"

---

What's different about GEML

Where each format lands on the four capabilities of the last chapter — addressing, projection, validation, rollback — is the table below; GEML stays small on purpose, and what it refuse