通用标记语言 geml-spec/geml

MCP Toplist Glama MCP server score Mentioned in Awesome MCP Servers Mentioned in Awesome AI Plugins Mentioned in Awesome Markdown

GEML — General Expressive Markup Language

GEML 是一门轻量标记语言，块结构统一、可寻址，动词标准化。
人读起来轻松，智能体改起来安全。 在智能体驱动的开发与知识工作中，纯文本和 Markdown 没有确定的块边界：程序和模型之间来回传递整个文件——好一点的情况是用行窗口去试探，改写时还要把原文逐字复述一遍。token 开销随文档长度增长，操作也变得臃肿。改写几轮之后，别处摘录的副本就开始走样。

目录： 解决什么问题 · LLM 需要什么 · 有何不同 · 1 分钟看懂格式 · 配置档 ·上手实践 · 配合 LLM 使用 ·成熟度与版本 · 设计思路 · 路线图 · 参与共建 ·许可证什么都不用改就能上手。 geml list、geml find 和 geml get 直接处理你已有的 Markdown——不转换、不新增文件，.md 还是 .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

只有那一节进入智能体的上下文——几 KB，不是整个文件，文件再长也一样。每次保存都是一个版本，可以读回，也可以回滚，回滚一节或整个文件都行。

▶ 在 Playground 里试试——不用安装，也不用先读什么。

需要比一节更细——一个块、一张图、一张表？让 .geml 站在中间地带：按这个粒度编辑，你导出的 --to md 永远不会和它走偏。

块有名字，块里的东西有坐标。 表格的单元格、data 块的叶子、meta 里的键——每个都有结构本身给出的坐标，get 和 set 正好落在那个值上。

geml get doc.geml '#fy[2]["Q1"]' # one cell
geml set doc.geml '#intake["fields"][1]["name"]' # one leaf in the JSON

对人来说，它是读起来干净的纯文本；对智能体来说，它是可寻址、可校验、可追溯、可回滚的 "Doc-as-a-Base"。

GEML 很精简。 它是纯文本——没有渲染器也照样干净；整个语言只有一种块语法；结构天生可寻址、可校验、可引用。

GEML 不为每种内容单独造一套迷你语法，而是把所有内容装进同一个容器：带类型的块。代码是块。表格、图表、数学公式、标注，甚至元数据也是块——一段散文也能是块（=== text），只要你想让它可寻址。以后扩展也一样简单。形状每次都相同，语言好学，也就不容易写错。

块有名字，动词才有落脚的地方——完整语法见一分钟看懂格式。

解决什么问题

解决的问题

1. 上下文负载与 token 膨胀：JSON/XML 带着沉重的包装语法，Markdown 缺少结构化元数据和引用；GEML 只读写目标块，上下文开销不再随文档长度增长。
2. AST 级精度与解析确定性：无结构文本经过多轮 LLM 读写会退化——格式损坏、语义漂移；GEML 的确定性语法映射到 AST，程序和 LLM 都能一次创建、读取、更新、删除一个块。
3. 文档副本碎片化：多智能体协作和共享流水线靠复制粘贴传递内容，副本越传越散；GEML 围绕单一事实来源构建，用标准引用和数据绑定取代副本。

核心特性

- AST 级结构化操作：文档解析成带类型的树；智能体定位目标，原地打补丁，幂等。写入以字节拼接落地，并做全文档重新校验，每个未触碰的字节保持原样。
- 低 token 读写：省下的不是标记字符，而是从未被读取的部分——#id 命中一个语义完整的块，其余内容根本不进入上下文。
- 单一事实来源，模块化引用：原生支持跨文档、跨片段引用；改一次源，所有引用自动跟随。
- 稳健的双向读写：整个语言只有一种块形态，好生成、难写错；严格校验器给出精确错误位置和修复反馈。
- 基于配置档的领域扩展：在 === meta 里声明 profile，即可添加领域词汇（设计样式、表单、代码图、媒体时间线），无需新语法；声明的词汇由自己的检查器校验，未知环境下安全回退到标准块。

LLM 需要什么样的文本格式？

AI 时代的文本「由模型产出，由人和模型共同阅读」。

共同阅读意味着可读性不能牺牲；而模型最终落在 Markdown 上，是找不到更好方案时的妥协，不是最终答案。

为人和模型协作而生的文本格式，应该改变机器读写的手感：

- 细粒度：按块精确寻址，块内按坐标寻址——不必再扫整个文件；
- 结构化：组织更好，能装的东西更灵活；
- 一致：一套标准读写接口，其他模态自然扩展；
- 零门槛：心智负担最小，迁移平滑、近乎零成本。

可我们现有的文本基础设施，没有一样是为这个场景设计的：

* Markdown（为人排版）：没有稳定的结构块，没有机器可用的键。改一个参数，智能体得读写整段文本——多轮循环里浪费上下文预算，格式和语义还都容易漂移。
* JSON / XML（为机器序列化）：满是包装语法和结构噪音——挡住人的自然阅读，还在长上下文里悄悄吃掉昂贵的 token。
* 草稿记忆和散落文件（没有单一事实来源）：上下文被撕碎在聊天记录和到处散落的 Markdown 副本里；副本一诞生就是漂移，版本错位和幻觉失真接踵而至。
三种失败，根子都在各自工具的优点上：Markdown「永不报错、什么都能写」，正是人敢自由书写的原因，也恰恰是机器无法信任读回来的结构的原因；JSON/XML 严格的 schema，正是机器确定性的来源，也恰恰是没人拿它写散文的原因。优点即缺陷，所以补丁修不好：给 Markdown 硬加一条「引用坏了就让构建失败」，违背它的契约；把 JSON 的外壳语法剥掉，又否定它的本性。当人和智能体开始高频共写同一份文本，需要的不是两极之间的折中，而是一种从第一天起就把「人可读」和「机器可操作」当作同一条设计约束的格式。

答案："Doc-as-a-Base"

GEML 是新格式，酒却是旧的：增强并统一 Markdown 式表达、剥掉 HTML 式表现语法，围栏块的想法来自 Markdown，#id 和嵌入来自 XML 与 AsciiDoc，行内投影来自 Obsidian，动词来自 Roy Fielding 博士论文里的 REST 架构风格。新的是用一个块容器把它们全装下。有点像 TypeScript 之于 JavaScript——语法没法兼容，但 list、get、set、add、delete 已经能用在手头的 Markdown 上。这个容器给纯文本文档一套标准的操作语义：

| 旧痛点 | 对应能力（四条法则） | 给开发者和智能体带来什么 |
| 改一处就要重写全文 | 寻址法则 | 每个块都带 #id；get/set 只读写那个块。没加载的东西坏不了——上下文窗口始终归你。 |
| 副本遍地，处处漂移 | 投影法则 | === embed 动态求值，不再复制粘贴；源头定义一次，同步副本的苦活就结束了。 |
| 坏格式 / 坏引用污染下游 | 校验法则 | 引用和语法在构建时检查；坏写入落地前就被拦下，不用等人审。 |
| 一次误改逼得整文件回滚 | 回滚法则 | 配套的 .gemlhistory 原子地回退单个块——不用拆掉整页；给智能体的轻量版本安全网。 |
文档不再只需要一种格式，它还需要一组动词。 GEML 保留纯文本的可读性，又加入确定性的块级操作。LLM 时代工程文档的两难，以及这些老做法为什么该装进同一个新的块容器，博客里有完整论述：「LLM 时代，我们需要一种新的文本格式吗？」

GEML 有什么不同

上一章讲了四项能力——寻址、投影、校验、回滚。每种格式在这四项上各处于什么位置，见下表；GEML 刻意保持小巧，它拒绝做什么，见我们如何考虑设计。

与其他格式的对比

这四项能力在各自领域都有成熟方案；不寻常的是，要用一种纯文本格式同时满足四项：

| 类别 | 状态到底是什么 | 可寻址 / 可引用 | 可投影 / 可嵌入 | 可校验 | 历史 / 可追溯 |
| Word / Docs | 不透明状态 | ❌ 没有块级键；只能通过平台 API 访问 | ❌ 只能复制粘贴 | ❌ 完全无法检查 | ⚠️ 平台服务端保存，不在文件里 |
| Markdown / AsciiDoc | 一串字符流 | ⚠️ 靠标题锚点或方言 id；没有读写动词 | ⚠️ 方言嵌入（Obsidian ![[…]]、include::）——静默失效 | ❌ 断链静默失败 | ❌ 格式内没有——得靠外部 git |
| JSON / XML | 数据序列化 | ✔️（id / schema） | ⚠️ 仅 XML（XInclude，外部） | ✔️ 靠外部工具链 | ❌ 格式内没有——得靠外部 git |
| GEML | 纯文本 + 块结构 | ✔️ 每块一个唯一 #id（原生可引用） | ✔️ === embed：引用即查找（原生） | ✔️ 构建时报错 | ✔️ 文件旁的 .gemlhistory（原生可追溯） |

逐项对比：对比 CommonMark · 对比 XML 和 JSON · 7 种格式的能力矩阵 · awesome-markdown 里的 Markdown 变体与工具（中文，HTML 页面）。

与 Markdown 共存：GEML 是编辑时的唯一事实来源，Markdown 是交付产物。用 geml <file> --to md|html 单向投影，照旧交付 .md 或 .html。是协作，不是锁定。 （投影有损：块 id 和绑定表格的图表过不去。）

别只听表格的——自己重跑一遍。 这是我问模型的原话：

根据你刚才编辑 README 的实际经验，描述你在文档上走的命令步骤（我看到你在用 grep 之类），以及你是否缓存文档来省 token——我们来对比一下，由此看看 GEML 的哪些部分真正值得存在。
回信来了：一次编辑要花多少代价 和 真实的一天回放。把问题贴给你自己的模型，看它怎么回答。
PS：我还在琢磨一件事：codemap 产出的上游链（谁调用它）和下游链（它调用谁），能不能用同样的方式锁定函数和调用点，并且改动项目代码。有结论了我会发一份报告。

一分钟看懂格式

类型化块

一种形状，所有类型。 块的基本语法是 === type [attributes] … ===（其中 {#id .class key=val} 这类属性可选）——变的只是 type（以及块体怎么读）：

=== code {lang=python}
print("hi")

=== note {.intro}
Parsed prose with emphasis and a [[#budget]] reference.

=== meta
title = "Budget plan"

一串 =（三个或更多）开启块；等长的一串关闭块；更长的围栏可以嵌套更短的围栏。带 #id 的块还可以用带标签的围栏 === #id 关闭——不用数围栏长度，长块因此很难写错（嵌套仍然需要更长的外层围栏：块体里等长的裸 === 会提前关闭块，带不带标签都一样）。类型决定块体怎么读——raw（原样：code、diagram、math、table）、flow（解析散文，带行内标记：note、text）或 data（每行一个 key=val：meta）；embed 完全不带块体——它的 src= 指明它代表哪个块——每个块都可以带属性对象 {#id .class key=val}，其中 .class 是语义标签，绝不是样式钩子。完整的行内语法（强调、链接、[[#id]] 自动引用、媒体、脚注、行内 $math$）见规范。

表格——两种块体，同一个模型

用可视方式写表格：

=== table {#budget caption="Annual cost"}
| Plan | Months | Rate |
| Basic | 1 | 30 |
| Pro | 2 | 30 |

……或者写成数据。表格保存事实；它上面的 view 派生出计算列和汇总行：

=== table {#fy25 format=csv header=1}
Segment, Q1, Q2, Q3, Q4
Cloud, 8, 10, 12, 14
Platform, 5, 6, 7, 9
Services, 3, 4, 4, 5

=== view {#fy25-report src=#fy25 compute="FY [%.1f] = Q1 + Q2 + Q3 + Q4; n = 1" summary="Segment = 'Total'; FY [%.1f] = sum(FY); n = sum(n)"}

两种表格写法描述同一个模型。FY 列和 Total 行由 view 在构建时算出：

| Segment | Q1 | Q2 | Q3 | Q4 | FY | n |
| Cloud | 8 | 10 | 12 | 14 | 44.0 | 1 |
| Platform | 5 | 6 | 7 | 9 | 27.0 | 1 |
| Services | 3 | 4 | 4 | 5 | 16.0 | 1 |
| Total | | | | | 87.0 | 3 |
compute 按行对列执行 + - * / ( )；summary 用聚合值 sum / avg / min / max / count 追加一行表尾（可在聚合值上做算术，比如加权比率）；末尾的 [printf] 设定数字显示格式。上面的 n 是行数惯用法 —— count 统计某一列的非空单元格，所以对常量列求和才是统计行数。

表格也能通过 src="regions.csv" 从外部 CSV 拉取数据。

数学

=== math {#gauss caption="Gaussian integral"}
\int_{-\infty}^ e^{-x^2} dx = \sqrt

$$\int_{-\infty}^ e^{-x^2} dx = \sqrt$$

图表 —— 托管 DSL，或给表格画图

GEML 从不解析图表主体；它把主体交给可插拔的渲染器（未知的 format 只给警告，主体原样保留）：

=== diagram {#flow format=mermaid caption="Review flow"}
graph LR
A[Draft] --> B{Review} -->|ok| C[Publish]

graph LR
A[Draft] --> B{Review} -->|ok| C[Publish]

图表还能给表格画图 —— 单一数据源，列引用在构建时校验，不复制数据：

=== diagram {format=geml-chart data=#fy25-report type=bar x=Segment y=FY}

数据取自上面的 #fy25-report 视图 —— FY 是计算列，所以图表绑定的是派生它的视图，而不是基表：

xychart-beta
title "FY by segment"
x-axis [Cloud, Platform, Services]
y-axis "FY"
bar [44, 27, 16]

数据 —— 是值，不只是文本

每种块类型都声明自己装什么：code 是一段代码，table 是网格，math 是公式。data 装的是数据值，数据格式就住在这里 —— json（默认）、jsonl，以及声明为子集的 yaml；toml 预留。带类型意味着主体会被读取，而不只是显示：少个逗号构建就失败，geml get --json 返回值本身，图表能直接读它。

=== data {#log format=jsonl}
{"ts":"09:00","p95":41}
{"ts":"09:10","p95":58}

jsonl 主体每行一条记录，程序可以在文件末尾盲追加。记录也能留在自己的文件里：src=ops/latency.jsonl#L900-999 指定文件，还可选一个行窗口 —— 日志照旧追加、照旧 tail，而文档是它经过校验、可寻址、可画图的视图。

嵌入 —— 动态引用，不是复制

一个块可以代表另一个块：同文档内用 src=#id，跨文档用 src=other.geml#id。嵌入是渲染时对源的动态查找 —— 改一次源，所有嵌入跟着变；删掉源，geml check 当场让构建失败。

=== embed {src=#fy25}

主体保持为空；目标放在 src= 里。
Markdown 无法展示投影效果。想实时查看：安装浏览器扩展，打开 sample.geml 的原始链接，滚动到 Transclusion 一节——同文档投影（src=#roadmap）、跨文档投影，甚至链式解析（一个嵌入拉取图表，图表本身又绑定到另一个文件里的表格）都会就地渲染：那里什么都没写，但只要改一次源文件，投影就会跟着变。

配置档——领域词汇表，像乐高积木一样拼装

想在文档里编写交互式表单、定义设计 token 系统，或者映射整个代码库的调用图？
在传统 Markdown 里，这得靠专有插件（:::note、自定义 JSX 标签），最终难免分裂成一堆互不兼容的方言孤岛。

GEML 用配置档（应用层词汇表，规范 §8.6）解决这个问题：一行声明，按需解锁领域专属的结构化超能力。

=== meta
profile = "geml-style/v1 geml-form/v1"

==== form {#signup handler=subscribe}
=== form-field {name=email label="Work email" type=text required pattern="[^@]+@acme\\.com"}

=== style-rule {#cta match="button.cta" bg="{{brand}}" radius="6px"}

扩展而不分裂

- 🧩 像乐高积木一样混搭：核心语法保持精简、冻结不变，领域词汇表在它旁边生长；调用图、设计 token、表单校验、版本历史……用一行 profile = "..." 就能组合好几个。
- ⚡ 不用写插件，工具链已经就位：新增领域块不需要 fork 解析器，也不需要自定义插件；它拿到的基础设施和其他所有块一样——确定性的 #id 寻址、geml get/set 按块变更、命令行动词、MCP 协议，以及自主 AI 智能体控制。
- 🛡️ 天生可移植，绝不锁定：扩展能力的同时不破坏互操作性；不认识某个配置档的处理器照样能读取每个块，并按 #id 寻址，所以文档换到别的工具里，结构依然完整。

已发布的标准配置档

| 配置档（指南） | 状态 | 用途 | 命令行 | 在线演示 / 示例 |
| geml-codemap/v1 | stable | 把代码库的调用图生成为 GEML 文档：每个方法一个块，你能看到谁调用它、它又调用了谁；前端和后端合并成一张图 | geml codemap build\|verify\|serve | 交互式调用图 |
| geml-media/v1 | draft | 用一份文档描述视频时间线：素材、片段、字幕轨和配音轨；导出为网页播放器，或用 ffmpeg 渲染成 MP4 | geml media build\|export\|lay\|todo | Doc-to-Video（通过 ffmpeg 把文档转成 MP4） |
| geml-style/v1 | draft | 颜色、间距和布局放在单独的样式表文档里，其中的规则作用于你的内容；内容文档本身保持不变 | geml style check | GitHub Blob 页面 1:1 复刻 |
| geml-history/v1 | stable | 把历史版本保存在文档旁边的 .gemlhistory 文件里：读取任意旧版本，恢复单个块，或回滚整个文件 | geml history save\|get\|restore | 原子块回滚工作流 |
| geml-form/v1 | draft | 用文档描述表单：有哪些字段、字段类型、哪些必填、允许的取值范围；浏览器扩展和演练场会画出预览 | — | 交互式复杂表单示例 |
| geml-translator/v1 | draft | 翻译文档里不存译文：它嵌入原文并指定目标语言，浏览器扩展在打开时机器翻译，因此译文始终跟随原文的每次改动 | — | 打开时翻译 |
| geml-statechart/v1 | draft | 用一个 diagram 块写出状态机：状态、带守卫和动作的迁移，以及守卫读取的变量；geml check 找出无法到达的状态和死胡同，--to html 画出图形，--to md 转成 Mermaid | — | — |

💡 想看看配置档实际跑起来的样子？
• geml-media 在线演示：一份剪辑文档加一条命令（geml media build ep01-cut.geml --out ep01.mp4 --burn-subs）就能调度 ffmpeg，对齐音视频、混合轨道，把字幕烧进成片（点这里看）。
• geml-style 在线演示：内容在 page.geml 里保持纯文本，样式和布局放在 github.style.geml 里——渲染出 GitHub blob 页面的 1:1 像素级复刻，不受 CSS 锁定（点这里看）。
• 表里每个配置档名称都能打开它的一页指南——讲它做什么、第一条命令、日常用法。如果你写代码，从 geml-codemap 开始。你也可以轻松创建自己的自定义域配置档。

下一步 — 立刻上手

▶ 在 Playground 里试着写 GEML — 左边编辑，右边实时渲染；七个章节从带类型的块和 #id 一路讲到坐标、数据、图表和投影，改错了当场标出来。不用安装，也不用先读什么。

然后，按你喜欢的顺序来：

1. 在浏览器里看它渲染。 安装 扩展，打开一个 .geml 原始链接（要原始文件，不是 GitHub 的 blob 页面——那个是 HTML）：GEML 规范本身（吃自己的狗粮——规范就是一份 GEML 文档，按规模渲染），showcase（一张计算出来的表格、四张图表、一个 Mermaid 流程图，还有数学公式），或者 playground/sample.geml，看交互式代码图。
2. 看一整页怎么从一份文档排出来。 样式演示 1:1 复刻了 GitHub 的 blob 页面——顶栏、文件树、面包屑、Preview/Code/Blame、下拉菜单——其中 page.geml 存所有字符串，github.style.geml 存所有颜色和长度，而查看器对两者一无所知。任何浏览器都能打开——页面由查看器自己的代码绘制——让它成立的 GEML 就在下面。
3. 在本地运行。 npm i -g @geml/geml（Node 22+），然后对文档跑 geml check，或者用 geml codemap build 指向你自己的仓库；在 Claude Code 上，npx -y @geml/geml skill install 会把写作技能、命令行和 MCP 服务器装好，用户全局生效，不改任何设置，也不装钩子（详情）。
4. 读语法，或者看它逐条规则走一遍。 完整规范（EN / 中文）是规范性的，一口气能读完；图解 GEML（EN 和中文）是十一个自包含页面，每种块类型一页，每个配置档一页，命令行也有一页：左边是 GEML，右边是处理器实际做的事（geml check 的诊断、geml list 的地址、--to html 的标记），每条规则都标了出处和状态。

配合 LLM 使用 GEML

目标只有一件事：让你的模型一次编辑一个块，并且验证——绝不为改一段话就重读、重发整个文件。一步就能做到：

| 你用 | 运行 |
| Claude Code、Gemini、Qwen | npx -y @geml/geml skill install — 写作技能、命令行和 MCP 服务器，用户全局生效；不改 settings.json，不装钩子（或者 claude plugin marketplace add geml-spec/geml，然后 /plugin install geml@geml） |
| Codex | 在本仓库的检出目录里启动它，插件就在 /plugins；不想克隆的话，见 integrations/codex-plugin/ |
| DeepSeek Harness | dsh plugin --profile web add @geml/dsh-plugin（源码） |
| 任意 MCP 客户端 | npx -y @geml/geml mcp --root .，或者什么都不装，直接用 https://geml-mcp.supermarket.workers.dev/mcp —— Cursor、VS Code 和 Claude Desktop 的配置见 docs/mcp-guide.md |

其他情况 —— 模型没有技能可读，就得把规则给它讲一遍。把下面的提示词粘过去，并始终用 geml check 把关它写回来的内容（命令行装法：npm i -g @geml/geml，需要 Node 22+）：

按 GEML 写文档：每个块都是 === type [attributes] … === （1 分钟看懂格式 列出了所有类型）。有四条规则模型最容易搞错：结束围栏是一串 =，长度与开头完全相同；正文里含 === 时，外层围栏要更长；标题只用 ATX #，不要 --- frontmatter（元数据用 === meta）；每个 #id 都唯一，每个引用（[[#id]]、text、[^id]、data=#id）都必须能解析；不支持原生 HTML。规范原文见 GEML-spec.md。

What it will do with it

geml list doc.geml # CALL FIRST: every block, its address, kind, lines
geml find "words" doc.geml # search block content -> an address, not a line number
geml get doc.geml '#hello' # read ONE block (a heading id = its whole section)
geml get doc.geml '#hello' --intro # a section cuts three ways: --head | --intro | --body
geml set doc.geml '#license' --in template.geml#mit # replace that block, forking another
geml add doc.geml --after '#intro' --in snippet.geml # insert a fragment (keeps its own ids)
geml revert doc.geml '#plan' --rev -1 # roll ONE block back
geml check doc.geml # validate only: diagnostics + exit code

Over MCP the same verbs are tools (geml set → geml_set), and two guarantees
make it better than letting a model rewrite the file: a write is parsed
before it reaches disk and refused if it would break the document, and every
write first records a .gemlhistory revision, so geml_revert can undo one
block. Paths stay confined to --root; a root that holds a code graph also
answers "who calls this". Every verb: the parser README;
every tool: docs/mcp-guide.md.

Ecosystem and maturity

- Spec 1.0 is stable, in English and 中文, and is itself written in GEML. MIME media type text/vnd.geml, registered with IANA.
- Two implementations pass the same conformance suite
of 800+ cases: the reference parser geml-parser/ (TypeScript, 2,300+
unit tests, coverage gated at 95%) and geml-parser-rs/ (Rust and
WebAssembly, written from the spec and the suite alone).
- Forward compatible by grammar: a processor degrades gracefully on what it doesn't
know (§8.2), so a new block type is not a breaking change. Releases: CHANGELOG.md.

How we thought about the design

What the design follows

1. Human–Agent Isomorphism, Not a Compromise: rather than splitting the difference between Markdown for people and JSON for machines, GEML treats "readable at a glance" and "operable with certainty" as one constraint — people get clean prose, agents get a strongly typed AST.
2. Doc-as-a-Base, Not a Stream of Characters: a document is a base of structured records with stable primary keys (#id); every block has its own lifecycle, coordinate and atomic CRUD interface, so an agent edits one block instead of rewriting the file.
3. One Syntax Primitive, Open Domain Vocabularies: a single typed-block primitive (=== type) carries code, data, tables, math and layout; domain vocabularies extend it through Profiles (profile = "..."), the grammar frozen and the vocabularies open, which keeps dialects from splintering it at the root.
4. Transclusion over Duplication: Kill the Incentive to Copy: a hyperlink is a signpost that invites copy-paste and drift; a GEML reference is a live viewport (=== embed) — define once at the source, project everywhere.
5. Compiler-Grade Integrity: Treat Documentation Like Code: where Markdown never fails and renders something, GEML validates at build time — a broken #id or a reference cycle fails with a non-zero exit, before bad data reaches anything downstream.
6. Local-First History, Not Cloud Lock-in or Git Overhead: versions live at block granularity in a .gemlhistory beside the document, with no cloud service and no whole-repo commit for a micro-edit; geml revert doc.geml '#id' rolls one block back.

What it therefore refuses

| Refused | Why |
| A diagram language of its own | External DSLs are hosted (Mermaid, Graphviz, D2, …); the format defines only the hosting protocol |
| A raw-HTML escape hatch | Semantics stay portable, tied to no backend or renderer |
| Setext headings / --- frontmatter | ATX # only, so nothing collides with a thematic break |
| A full spreadsheet engine | Per-row formulas and summary aggregates are enough; no cell addressing, lookups, or macros |

Roadmap

- [x] Spec and implementations: the GEML 1.0 specification, in English and Chinese, with a conformance suite and the geml-history/v1 profile that defines the .gemlhistory sidecar; the reference implementation @geml/geml (parser, CLI, block-level .gemlhistory tracking); a second implementation, geml-parser-rs/ — Rust, compiled to WebAssembly, written from the spec and the conformance suite alone, without reading the reference parser
- [x] The MIME media type text/vnd.geml registered with IANA (2026-10-26), with the spec as its published specification and the project as change controller
- [x] Tools: the official MCP server (geml mcp) for Claude Code, Cursor, Codex and other MCP hosts; codemap, a whole codebase's call graph written as GEML; the VS Code extension on the Visual Studio Marketplace (publisher geml)
- [x] Ecosystem integrations: VS Code highlighting and reference checking, tree-sitter, Obsidian, Logseq (two-way sync against a live DB graph), the browser viewer, a GitHub Action, LangChain / LlamaIndex, and the agent-harness plugins — Claude Code, Codex, Grok, DeepSeek Harness, plus root manifests for Gemini CLI and Kimi Code
- [ ] The Logseq plugin listed in the Logseq marketplace (PR #893) and the Grok plugin listed in xai-org/plugin-marketplace
- [ ] Implementations by other hands — in whatever language you write; the spec and the conformance suite are public, and we are glad to help line them up

Where it runs

The CLI @geml/geml · the browser Chrome extension · VS Code · IntelliJ / Android Studio (build from source) · a GitHub Action · LangChain / LlamaIndex (reference implementation) · the Playground, with nothing to install.

Take part

1.0 means the rules already there won't shift under you — not that the design is settled, and there is one author behind both implementations so far.

- Write a parser in your language — how; finding where the spec is ambiguous is itself the contribution.
- Argue with the drafts — GEP-0008 and GEP-0010, or start a discussion.
- Claim a piece — the open gaps, and the repository layout, are in CONTRIBUTING.md.

License & governance

Code is MIT (LICENSE); the specification documents are CC-BY-4.0
(spec/LICENSE-spec.md lists them). Anyone may build a
conformant implementation without permission; how decisions are made and how to use
the name: GOVERNANCE.md.