Files
marqdo/doc/tutorial/README.md
T
cflmyandCursor 7645dd4c1f Extend network stack: session/auth, WebSocket, cookie/multipart primitives
Add the network-extension wave to lib/net and the web ABI plugin:
- lib/net cookie_parse / multipart_parse host primitives (EN/ZH)
- plugins/web session store + /admin login gate + WebSocket client/server
- ext/web author surface (EN/ZH) for session, auth, ws
- form update flow and page-level validation echo tests
- fix string escapes: \xHH, \u{...}, unknown escapes kept verbatim
- map Chinese component slots (导航/侧栏/页脚) so sidebar renders
- resolve relative static/db paths against the entry script dir (entry_dir)
- new tutorial chapter 14, EN/ZH example sites, and gold tests

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-25 14:58:46 +08:00

95 lines
3.4 KiB
Markdown

# Marqdo 语法教程
> **代码即文档,文档即代码。** Marqdo 把 Markdown 的标记当作编程语法:同一个 `.mq.md` 文件既是给人读的文稿,也是给机器跑的程序。
本教程面向所有读者——从没写过代码的文档作者,到熟悉 Python 的工程师。每章都配有可直接运行的完整示例。
## 目录
### 第一部分 · 入门
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 1 章:Marqdo 是什么](./01-入门.md) | 理念、安装、第一个程序、运行 | 写出并运行你的第一个 `.mq.md` 程序 |
| [第 2 章:基本语法](./02-基本语法.md) | 文件结构、注释、标识符、字面量 | 看懂 `.mq.md` 里哪些是代码、哪些是注释 |
### 第二部分 · 变量与数据
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 3 章:变量与赋值](./03-变量与赋值.md) | 绑定、变量引用、字符串 | 存取值,拼接文本 |
| [第 4 章:输出与输入](./04-输出与输入.md) | `print` / `打印`、`input` / `输入` | 与用户交互 |
| [第 5 章:运算符与比较](./05-运算符与比较.md) | 算术、比较、逻辑 | 计算与判断 |
### 第三部分 · 流程控制
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 6 章:函数](./06-函数.md) | 定义、参数、返回值、函数结束 | 封装可复用逻辑 |
| [第 7 章:条件分支](./07-条件分支.md) | `1.` `2.` 分支、else | 让程序根据条件走不同路线 |
| [第 8 章:循环](./08-循环.md) | `-` 遍历、`-` while | 重复执行 |
### 第四部分 · 数据集合
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 9 章:集合(表格)](./09-集合.md) | 列表、字典、记录、脚注取元 | 用 Markdown 表格组织数据 |
### 第五部分 · 面向对象与模块
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 10 章:对象与方法](./10-对象与方法.md) | `#` 类型、构造、方法、继承 | 面向对象编程 |
| [第 11 章:模块与导入](./11-模块与导入.md) | frontmatter、import、库路径、短名 | 组织大型项目 |
### 第六部分 · 进阶
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 12 章:标准库](./12-标准库.md) | 内置函数、`lib/` 模块 | 直接使用官方能力 |
| [第 13 章:命令行工具](./13-命令行工具.md) | `run` / `view` / `debug` / `catalog` | 运行、浏览、调试、发布 |
| [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) | `lib/net`、`ext/web`、鉴权、WebSocket | 构建 HTTP 客户端与网页应用 |
---
## 快速示例
一个完整的 Marqdo 程序长这样:
```markdown
# main
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello, `谁`!
---
## 加一
+ `n`
**n + 1**
```
- `# main` —— 入口
- `> 问候 谁=World` —— 调用函数(具名参数)
- `## 问候` + `+ `谁`` —— 定义函数及其参数
- `> print text=…` —— 输出(副作用,是普通函数)
- `**n + 1**` —— 返回值
- 单独一行 `---` —— 结束函数体
---
## 运行方式
```bash
marqdo run 文件.mq.md
```
更多运行、浏览、调试、发布方式见 [第 13 章](./13-命令行工具.md)。
> **提示**:语法宪法与精确定义见 [`doc/design/markdown-mapping.md`](../design/markdown-mapping.md);本教程是它的通俗讲解版。