Point editors to the vscode-extension branch for host work, mirroring the public/gh-pages split. Co-authored-by: Cursor <cursoragent@cursor.com>
131 lines
5.4 KiB
Markdown
131 lines
5.4 KiB
Markdown
# Marqdo
|
||
|
||
**代码即文档。文档即代码。文档即知识库。**
|
||
|
||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
|
||
|
||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||
|
||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 `vscode-extension`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
|
||
|
||
---
|
||
|
||
## 为什么重要
|
||
|
||
| 痛点 | Marqdo 的答案 |
|
||
|------|----------------|
|
||
| 文档过期、示例跑不通 | **一份源文件**:叙述、结构与执行结果同源 |
|
||
| 知识散落在 Wiki / 注释 / 脚本里 | **`.mq.md` 即知识单元**,可浏览、可运行、可检索 |
|
||
| 人写给人看,AI / 工具另起一套 | **人机同读同写同构**:标记语言对人类友好,对解释器确定 |
|
||
| 大仓里「文档站」与「代码仓」脱节 | `view` 文档站 + `debug` 调试面 + `catalog` 清单,同一棵树长大 |
|
||
|
||
这不是「再做一个 Markdown 渲染器」,而是:**把文档升格为可解释的程序与可生长的知识库**,让协作在大型项目里依然站得住。
|
||
|
||
---
|
||
|
||
## 语法速览(v0.1)
|
||
|
||
| 标记 | 含义 |
|
||
|------|------|
|
||
| 无标记行 | 注释(空行分段) |
|
||
| `*…*` | 程序语句 |
|
||
| `**…**` | **返回值**(架构) |
|
||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||
| `#` / `##` | 函数与作用域 |
|
||
| `+` / `1.` | 分支(臂头单独 `*` = else) |
|
||
| `-` | 循环(头下纯名则为形参) |
|
||
| 表格 | 集合 |
|
||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
||
|
||
```markdown
|
||
# main
|
||
|
||
> 问候 谁=World
|
||
|
||
## 问候
|
||
- 谁
|
||
|
||
> print text=Hello `谁`!
|
||
|
||
---
|
||
|
||
## 加一
|
||
- n
|
||
|
||
**`n` + 1**
|
||
```
|
||
|
||
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
|
||
|
||
---
|
||
|
||
## 理念
|
||
|
||
1. **叙述默认安全**(无标记 = 注释)。
|
||
2. **返回是架构;打印只是函数。**
|
||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||
|
||
---
|
||
|
||
## OKF 风格清单(自动生成)
|
||
|
||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||
|
||
```bash
|
||
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](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||
|
||
```bash
|
||
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](https://cflmy.github.io/marqdo/)
|
||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||
|
||
```bash
|
||
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/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
|
||
|
||
---
|
||
|
||
## 命名
|
||
|
||
**Marqdo** = Marq(Markdown)+ do(执行)
|
||
|
||
## 许可
|
||
|
||
[Apache License 2.0](LICENSE)
|