cflmyandCursor 117a03ca8e Initialize Marqdo vision docs and OKF-inspired design notes.
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>
2026-08-04 09:51:39 +08:00
2026-08-04 09:17:24 +08:00

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」,而在于:

  1. 叙事结构与程序结构同源;
  2. 类型与函数是文档中的一等段落,而非被围栏隔离的异类;
  3. 读者与执行者看到的是同一份真相。

我们关心的设计问题

后续设计将围绕这些问题展开(非完整列表):

  • 边界:哪些 Markdown 结构是程序结构?哪些只是散文?
  • 求值与排版:同一文本如何无损地同时服务解析器与渲染器?
  • 类型与证明:类型信息如何既服务检查,又服务阅读?
  • 模块与长文:大型程序如何仍像一本可导航的书,而不是一堵墙?
  • 交互文档:渲染结果能否嵌入可运行示例、求值结果、实时预览?
  • 互操作:如何与现有语言、工具链、包生态共存?

现状

Marqdo 处于思想与语言设计阶段。各阶段开发文档集中在 doc/:

  • 设计原则与决策记录(ADR)
  • 调研笔记(含对 OKF 等相邻标准的借鉴)
  • 语法草案与示例
  • 参考实现(解析 · 渲染 · 求值)
  • 工具与编辑器支持

欢迎讨论理念与设计;实现会随后跟上。


命名

Marqdo = Marq(mark / Markdown)+ do(行动、执行)。

标记是为了被人读懂;do 是为了被机器执行。两者不应再分家。


许可

Apache License 2.0

S
Description
No description provided
Readme
19 MiB
0 Stars 1 Watchers 0 Forks
Languages
Rust 82.1%
Go 12.7%
JavaScript 2.5%
Python 1.3%
CSS 0.5%
Other 0.8%