- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
4.2 KiB
Executable File
Web 布局工程:先拆布局,直到 Markdown 叶子
| 项目 | 内容 |
|---|---|
| 状态 | Active,2026-11-08 可执行参考工程与浏览器门禁已落地 |
| 包内手册 | 英文根入口 · 中文根入口 |
| 布局工具 | layout · 布局 |
| 实现与边界 | Web 手册优化 · Artifact · ADR 0007 |
先建立区域树,再写内容
首页先拆成导航、主体、页脚。页脚若有左右两栏,拆成品牌与链接;链接区若还有双栏,再拆成文档与社区。继续按内部独立布局拆分,直到叶子只剩简单 Markdown 可以直接表达的内容。
index.mq.md → components/index.mq.md(纵排)
├─ nav/index.mq.md → content.md
├─ main/index.mq.md → content.md
└─ footer/index.mq.md(分栏)
├─ brand/index.mq.md → content.md
└─ links/index.mq.md(分栏)
├─ docs/index.mq.md → content.md
└─ community/index.mq.md → content.md
父文件只导入子块、合并兄弟节点并声明一层排列。叶子文件只说明一种内容职责;内容较长时,使用相邻的普通 content.md,避免字符串转义。拆分终点不是行数或文件数量,更不是每句话建一个文件。
何时继续拆、何时停止
| 观察 | 决定 |
|---|---|
| 导航、正文、页脚混在一个内容块 | 拆成父级装配和三个职责块 |
| 页脚内部仍同时负责品牌与链接排布 | 再拆左右子块 |
| 链接子块内部仍包含两个独立栏目 | 继续拆到各栏目 Markdown |
| 叶子只包含标题、段落、列表、链接、表格、图片 | 停止;已可用普通 Markdown 表达 |
| 父文件含大量正文、HTML 标签、CSS 字符串 | 职责或表达方式仍未收敛,继续拆解 |
| 结构已经简单,只为减少行数而再拆 | 不必拆;以可读职责为准 |
表单、数据源、交互各有自己的领域职责,应调用对应模块,不以“Markdown 不表达交互”为由恢复整页 HTML 壳。只有确实需要兼容宿主能力时,才在隔离边界使用已有 raw/css 接口并说明原因。
同一表结构贯穿所有层
公共列是 type | slot | value | attrs | style,中文可用 类型 | 槽 | 值 | 属性 | 样式。使用 @ 记录表产生节点列表。
component.markdown/组件.正文:叶子值为普通 Markdown。component.wrap/组件.包裹:值中保留子节点列表,可标记 nav/footer/section 等语义区域。layout.stack/布局.纵排:声明上下关系。layout.columns/布局.分栏:声明响应式横向栏目。merge:只确定兄弟顺序,不会自动产生双栏,也不提前渲染 HTML。
原生运行时提供基本布局几何,窄屏自动折叠。style 列引用类名,不承载 CSS 源码,也不会自动定义主题。父块始终保留结构值;先渲染子块再拼 HTML 会丢失这条统一路径。
从文件走到真正页面
英文参考工程与中文参考工程实现上面的整个拆分树。先运行 preview.mq.md 检查真实渲染,再进入工程目录运行 serve.mq.md。
结构化 Document 显式声明 view: main / 视图: main,main 返回节点;服务启动时装配一次。普通 Markdown Document 保留既有行为,Endpoint 单独处理请求期互动。改动结构或叶子内容后重启。自动数据源绑定继续使用普通 Document,避免与启动装配混用。
验收同时检查源码和产物:叶子只含普通 Markdown,父文件只表达其一层关系;桌面页脚出现真正的两层分栏,手机两层都折叠;关于页、API 仍能工作。规则清单本身不是“已经通过”的证明。
cargo test --locked --test web_handbook
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
详细测试方式和当前能力边界见优化记录。