feat(markup): code-as-docs narration surface (G1–G4) and drop --- body end

Treat --- as Markdown HR everywhere, end side-effect helpers with empty returns,
and accept soft emphasis, float literals, and dynamic footnote keys so LLM-friendly
.mq.md stays runnable. Ship the weekend coffee example plus gold fixtures.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-14 10:16:48 +08:00
1 parent b5c07385e9
commit 5e74ff39f2
28 files changed
+799 -99

No files matched your search

+21
View File
@@ -0,0 +1,21 @@
# 代码即文档 · 周末咖啡手账
可读可跑的 v0.3 样例:`.mq.md` 同时是说明文和程序。
```bash
marqdo run examples/code-as-docs/index.mq.md
```
## 这份样例在示范什么
| 习惯 | 写法 |
|------|------|
| 数据给人读 | GFM 表当菜单 / 订单 |
| 步骤嵌在句子里 | `**总额 = 价 * 杯数**`、返回 `*总额*` |
| 装饰性强调 | `**说明**` 不执行(见设计 G2) |
| 段落分隔 | 顶层或体内的 `---` 只是分割线 |
| 浮点 | `折扣`=0.85 |
| 动态键 | `` 菜单[^`名`] `` |
| 调用 | 粗体赋值右侧 **可省略 `>`**:`**摘要 = 结账摘要 …**`;输出可用 `**打印 内容=…**` |
相关设计:[code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md)、[markdown-mapping-v0.3.md](../../doc/design/markdown-mapping-v0.3.md) §6。
+85
View File
@@ -0,0 +1,85 @@
---
title: 代码即文档 · 周末咖啡手账
description: >-
一份可读可跑的周末手账:菜单是表,计价写在段落里,主流程像日记。
展示叙述统一写法、装饰性强调、分隔线、浮点折扣、动态脚注键,以及粗体内免 `>` 的调用。
---
本文件既是**说明**也是**程序**。人读得到段落与表格;机器执行嵌在叙述里的粗体步骤,并把斜体当作返回值。
不必回避 Markdown 强调——不像代码的 `**说明**` 只是装饰。段落之间也可以用分隔线:
---
## 单价
一杯标价为`价`的饮品,默认`杯数`=1。先算**总额 = 价 * 杯数**,再返回*总额*。
## 会员折
会员单需要原价`原价`;门店默认八五折,写作`折扣`=0.85。
先算**应付 = 原价 * 折扣**,再返回*应付*。
## 结账摘要
客人点了`品名`,单价`价`,杯数`杯数`=1;是否`会员`=False。
小计交给单价:**小计 = 单价 价=`价` 杯数=`杯数`**。
1. `会员`
**实付 = 会员折 原价=`小计`**
**标签 = "会员价"**
2. *
**实付 = 小计**
**标签 = "原价"**
拼成一句给人对账的话,然后返回:
**文案 = 品名 + " ×" + 杯数 + " → " + 标签 + " " + 实付**
*文案*
## 加一
对于输入`n`,执行**n=n+1**接着返回*n*。
# main
周末手账从一张菜单开始。数据用表格写——人一眼能读,程序把它当成字典:
`菜单` =
| 美式 | 拿铁 | 燕麦拿铁 |
|------|------|----------|
| 18 | 28 | 32 |
---
第一单:会员双杯拿铁。品名先记在变量里,再用动态键取价;粗体赋值右侧是调用时不必再写 `>`:
**名 = "拿铁"**
**摘要 = 结账摘要 品名=`名` 价=菜单[^`名`] 杯数=2 会员=True**
**打印 内容=`摘要`**
对照一单非会员美式——品名已知,静态键即可:
**对照 = 结账摘要 品名="美式" 价=菜单[^美式]**
**打印 内容=`对照`**
---
也可以把今日订单写成行表。循环里把行字段直接传给结账,少一层临时变量:
`今日订单` =
| @ | 品名 | 单价 | 杯数 | 会员 |
|---|------|------|------|------|
| 1 | 燕麦拿铁 | 32 | 1 | True |
| 2 | 美式 | 18 | 2 | False |
- [`行`](`今日订单`)
**一行 = 结账摘要 品名=行[^品名] 价=行[^单价] 杯数=行[^杯数] 会员=行[^会员]**
**打印 内容=`一行`**
最后用加一收个尾,确认叙述里的位置调用也通:
**试算 = 加一 41**
**打印 内容=`试算`**