Introduce README, doc tree, and the decision that YAML manifests are tool-generated (not hand config) for deps and project docs. Co-authored-by: Cursor <cursoragent@cursor.com>
Marqdo
代码即文档。文档即代码。
Marqdo 是一门正在设计中的编程语言:源文件既是可执行程序,也是可被 Markdown 渲染的文档。写法本身就是叙述;运行与阅读共用同一份文本,而不是两套彼此漂移的产物。
为什么需要一门新语言
传统工作流里,代码与文档是两套工件:
| 代码 | 文档 | |
|---|---|---|
| 写给谁 | 机器 / 编译器 | 人 |
| 保真度 | 精确、可执行 | 易读、可解释 |
| 典型命运 | 持续演进 | 逐渐过时 |
我们用注释、README、Wiki、生成器去弥合裂缝,但裂缝从未真正消失——文档写完的那一刻,就开始落后于代码。
Literate Programming 把叙事与代码交织,仍是「文档里嵌代码」。
Markdown + 代码块 适合演示,不适合构建真实系统。
注释生成文档 能提取签名与说明,却无法保证叙事与实现同构。
Marqdo 想走第三条路:语言的语法与语义从一开始就按「可渲染、可阅读、可执行」一起设计,而不是事后把代码「翻译」成文档。
核心理念
1. 同一份源,两种阅读
一份 .mq.md 源文件:
- 对机器:是完整的程序——可解析、可类型检查、可执行。
- 对人 / 渲染器:就是 Markdown——GitHub、编辑器预览、静态站点无需转换即可阅读。
后缀选用 .mq.md,刻意让「可被 Markdown 工具链直接渲染」成为默认能力,而不是可选插件。
手写的只有源。 依赖与模块元数据由工具链分析 .mq.md 后,生成 OKF 风格的 YAML/Markdown 清单(类比其它语言由工具维护的依赖描述),并可自动汇总成本项目的目录文档——不是给人填的配置文件。详见 设计草案。
不是「从代码生成文档」,也不是「从文档提取代码」。源文本本身就是程序与说明;生成清单只是全项目的结构化投影。
2. 语法即排版
若代码要自动成为好文档,语法就不能只对解析器友好。
Marqdo 的设计约束包括:
- 结构即层级 — 模块、类型、函数的嵌套应对应文档的标题层级,而不是依赖额外的
@section注解。 - 命名即语义 — 标识符、契约、类型应能在渲染后直接读懂,少依赖旁白式注释。
- 声明即说明 — 接口、不变量、副作用边界写在语言里,而不是散落在散文里。
- 噪声极低 — 括号、分号、样板代码若无法帮助理解,就不应存在。
一门「看起来像 Markdown」却无法严肃编程的语言会沦为玩具;一门「能编程」却渲染成乱码的语言则失去初衷。Marqdo 必须同时成立。
3. 可读性是一等公民
多数语言把可读性交给风格指南与格式化工具。Marqdo 把可读性抬升为语言语义的一部分:
- 良好的程序应当读起来像一篇写清楚的说明。
- 糟糕的抽象、含糊的命名、隐式的副作用,不仅是工程问题,也是文档失败。
- 工具链(格式化、诊断、预览)的目标是:打开源文件时,你已经在读文档;运行它时,你已经在跑程序。
4. 设计优先于实现
「代码即文档」听起来简单,落地极难。它要求我们在以下张力之间找到平衡:
表达力 ↔ 简洁性
精确性 ↔ 可读性
可组合性 ↔ 叙事流畅
机器友好 ↔ 人类友好
没有深思熟虑的语法、类型与模块设计,这门语言很容易退化成「带一点 Markdown 装饰的脚本」。因此 Marqdo 会先把语言设计做对,再推进解释器、编译器与生态——宁可慢,不可歪。
愿景一瞥
理想中的 Marqdo 程序,打开时像文档,运行时像程序:
# 购物车
维护一组商品行,并给出应付总额。
## 行项目
一行包含名称、单价与数量。
type Line =
name: Text
price: Number
qty: Number
## 总额
总额是所有行的 `price × qty` 之和。
fn total(cart: [Line]) -> Number =
cart |> map(l => l.price * l.qty) |> sum
以上仅为思想示意,不是最终语法。真实语法将在设计文档中逐步敲定。
关键点不在于「看起来像 Markdown」,而在于:
- 叙事结构与程序结构同源;
- 类型与函数是文档中的一等段落,而非被围栏隔离的异类;
- 读者与执行者看到的是同一份真相。
我们关心的设计问题
后续设计将围绕这些问题展开(非完整列表):
- 边界:哪些 Markdown 结构是程序结构?哪些只是散文?
- 求值与排版:同一文本如何无损地同时服务解析器与渲染器?
- 类型与证明:类型信息如何既服务检查,又服务阅读?
- 模块与长文:大型程序如何仍像一本可导航的书,而不是一堵墙?
- 交互文档:渲染结果能否嵌入可运行示例、求值结果、实时预览?
- 互操作:如何与现有语言、工具链、包生态共存?
现状
Marqdo 处于思想与语言设计阶段。各阶段开发文档集中在 doc/:
- 设计原则与决策记录(ADR)
- 调研笔记(含对 OKF 等相邻标准的借鉴)
- 语法草案与示例
- 参考实现(解析 · 渲染 · 求值)
- 工具与编辑器支持
欢迎讨论理念与设计;实现会随后跟上。
命名
Marqdo = Marq(mark / Markdown)+ do(行动、执行)。
标记是为了被人读懂;do 是为了被机器执行。两者不应再分家。