cflmyandCursor 1271aafcdd Package release zips with stdlib and document bare-exe limits.
Ship recommended marqdo.exe+lib bundle, a separate stdlib zip, and clear release notes that the standalone exe does not include lib/.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 15:50:10 +08:00
2026-08-04 09:17:24 +08:00

Marqdo

代码即文档。文档即代码。文档即知识库。

Marqdo 把 Markdown 标记当作编程语法:同一个 .mq.md 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。

欢迎访问 marqdo 官方网站 阅读更多特性与可执行文档。

语法宪法:doc/design/markdown-mapping.md · 调用实参:call-arguments.md · 用户站:user-site.md · 浏览:view.md · 调试:view-debug.md · 金样例:tests/ · 用户文档:public/


为什么重要

痛点 Marqdo 的答案
文档过期、示例跑不通 一份源文件:叙述、结构与执行结果同源
知识散落在 Wiki / 注释 / 脚本里 .mq.md 即知识单元,可浏览、可运行、可检索
人写给人看,AI / 工具另起一套 人机同读同写同构:标记语言对人类友好,对解释器确定
大仓里「文档站」与「代码仓」脱节 view 文档站 + debug 调试面 + catalog 清单,同一棵树长大

这不是「再做一个 Markdown 渲染器」,而是:把文档升格为可解释的程序与可生长的知识库,让协作在大型项目里依然站得住。


语法速览(v0.1)

标记 含义
无标记行 注释
*…* 程序语句
**…** 返回值(架构)
> print … 等 输出等副作用 = 普通函数,非架构标记
# / ## 函数与作用域
+ / 1. 分支(臂头单独 * = else)
- 循环(头下纯名则为形参)
表格 集合
--- / *** 可选:框住分支/循环(不强制)
# main

> print text=Hello World!

## 加一
    - n

**`n` + 1**

理念

  1. 叙述默认安全(无标记 = 注释)。
  2. 返回是架构;打印只是函数。
  3. 代码即文档即知识库:文稿可执行,执行可回看结构,结构可导航与调试。
  4. 计划对齐 OKF 规范:依赖与模块清单由工具生成(marqdo catalog / sync),不是手填配置——知识图谱与仓库结构同源生长。见 catalog-cli.md。
  5. 正经解释器(Rust):词法/行分类 → 语法 → 语义 → 树遍历(及字节码);不用 Flex/Bison。见 路线图。

现状(v0.1.0)

  • 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 tests/
  • marqdo view:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
  • marqdo debug:独立调试页(断点 / 单步 / locals;默认端口 7430)
  • 标准库:文本、文件、系统、时间、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 -- view output public -o public
powershell -File ./scripts/build-public.ps1
cargo run -- catalog tests -o .marqdo

发布包(GitHub Releases):单独 .exe 不含 lib/;请下载带 lib/ 的 zip,或另下 *-stdlib.zip 解压到可执行文件旁(亦可设 MARQDO_LIB)。

文档:用户站 public/ · 设计 doc/ · OKF / catalog catalog-cli.md · 调试 view-debug.md


命名

Marqdo = Marq(Markdown)+ 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%