Point editors to the vscode-extension branch for host work, mirroring the public/gh-pages split. Co-authored-by: Cursor <cursoragent@cursor.com>
Marqdo
代码即文档。文档即代码。文档即知识库。
Marqdo 把 Markdown 标记当作编程语法:同一个 .mq.md 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
欢迎访问 marqdo 官方网站 阅读更多特性与可执行文档。
语法宪法:doc/design/markdown-mapping.md · 调用实参:call-arguments.md · 用户站:user-site.md · 浏览:view.md · 调试:view-debug.md · OKF 清单:catalog-cli.md · VS Code 扩展:vscode-extension.md(分支 vscode-extension) · 金样例:tests/ · 用户文档:public/
为什么重要
| 痛点 | Marqdo 的答案 |
|---|---|
| 文档过期、示例跑不通 | 一份源文件:叙述、结构与执行结果同源 |
| 知识散落在 Wiki / 注释 / 脚本里 | .mq.md 即知识单元,可浏览、可运行、可检索 |
| 人写给人看,AI / 工具另起一套 | 人机同读同写同构:标记语言对人类友好,对解释器确定 |
| 大仓里「文档站」与「代码仓」脱节 | view 文档站 + debug 调试面 + catalog 清单,同一棵树长大 |
这不是「再做一个 Markdown 渲染器」,而是:把文档升格为可解释的程序与可生长的知识库,让协作在大型项目里依然站得住。
语法速览(v0.1)
| 标记 | 含义 |
|---|---|
| 无标记行 | 注释(空行分段) |
*…* |
程序语句 |
**…** |
返回值(架构) |
**** / ** + 空白 + ** |
空返回(None),并结束本函数体 |
> print … 等 |
输出等副作用 = 普通函数,非架构标记 |
# / ## |
函数与作用域 |
+ / 1. |
分支(臂头单独 * = else) |
- |
循环(头下纯名则为形参) |
| 表格 | 集合 |
函数体内单独一行 --- / *** |
结束本函数体(无返回值收束;见 mapping §11) |
文件开头成对 --- … --- |
Frontmatter(元信息 / 导入),与函数结束符消歧 |
# main
> 问候 谁=World
## 问候
- 谁
> print text=Hello `谁`!
---
## 加一
- n
**`n` + 1**
完整约定:markdown-mapping.md。
理念
- 叙述默认安全(无标记 = 注释)。
- 返回是架构;打印只是函数。
- 代码即文档即知识库:文稿可执行,执行可回看结构,结构可导航与调试。
- 对齐 OKF(Open Knowledge Format)方向:清单由工具从
.mq.md自动生成,不是手填配置——见下节与 catalog-cli.md。 - 正经解释器(Rust):词法/行分类 → 语法 → 语义 → 树遍历(及字节码);不用 Flex/Bison。见 路线图。
OKF 风格清单(自动生成)
从源码派生 YAML / Markdown 知识包(勿手改生成物):
marqdo catalog [PATH] -o OUT_DIR
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
| 参数 | 默认 | 说明 |
|---|---|---|
PATH |
. |
工程根或含 .mq.md 的目录 |
-o / --out |
.marqdo |
输出目录 |
产物示例:catalog.yaml、index.md、modules/*.md(type: Marqdo Module 等)。设计见 generated-yaml-manifest.md · 调研 okf-and-marqdo.md。
cargo run -- catalog public -o .marqdo
# 或已安装二进制时:
marqdo catalog public -o .marqdo
现状(v0.1.0)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在
tests/ marqdo view:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)marqdo debug:独立调试页(断点 / 单步 / locals;默认端口 7430)marqdo catalog/sync:OKF 风格 YAML + 模块概念页- 标准库:文本、文件、系统、时间、JSON、网络、数学(公式/绘图)、外联(Python 等)
- 用户静态站:
public/→view output→ CI 发布 gh-pages - 选型:ADR 0001 — Rust
cargo run -- run tests/structure/hello.mq.md
cargo run -- run tests/structure/hello.mq.md --backend bytecode
cargo run -- view public --no-open
cargo run -- debug public --no-open
cargo run -- catalog public -o .marqdo
cargo run -- view output public -o public
powershell -File ./scripts/build-public.ps1
发布包(GitHub Releases):单独 .exe 不含 lib/;请下载带 lib/ 的 zip,或另下 *-stdlib.zip 解压到可执行文件旁(亦可设 MARQDO_LIB)。
文档:用户站 public/ · 设计 doc/ · OKF / catalog catalog-cli.md · 调试 view-debug.md
命名
Marqdo = Marq(Markdown)+ do(执行)