看板 Markdown 映射说明
周计划看板 · Markdown 映射说明
看板数据统一存放在 content/kanban/（一个 .md 文件 = 一个自然周）。
Zola 构建时将原始 Markdown 内嵌到页面，规则引擎直接解析，无需 static/ 副本。
文件命名
| 规则 | 示例 |
|---|---|
| 以本周周一日期命名 | 2026-06-16.md（对应 6.16 – 6.22） |
| 路径 | content/kanban/2026-06-16.md |
Front Matter（页面元数据）
+++
title = "6.16 – 6.22 周计划"
description = "列表页摘要，可选"
date = 2026-06-16
template = "kanban.html"
[extra]
week_start = "2026-06-16"
week_end = "2026-06-22"
core_tasks = "本周核心任务一句话"
stats = { total = 8, done = 3, todo = 3, doing = 2 }
+++| 字段 | 说明 |
|---|---|
week_start / week_end | 可编辑窗口（含首尾日；截止日 23:00 前仍可编辑，时区见 zola.toml extra.timezone） |
core_tasks | 列表卡片展示的核心任务 |
stats | 进度统计（按列名自动计算） |
结构映射
| Markdown | 看板元素 |
|---|---|
# 列表名 | 一列（待办 / 进行中 / 已完成 / 资源 / 目标） |
## 卡片标题 | 一张卡片，归属上方最近的 # 列表 |
列顺序 = 文件中 # 出现顺序。
卡片顺序 = 各列内 ## 出现顺序。
卡片属性 · 规则引擎指令
指令单独占一行，写在 ## 标题 之后、正文之前。以 @ 开头，大小写不敏感。
| 指令 | 语法 | 看板表现 |
|---|---|---|
| 截止日期 | @due 2026-06-20 | 卡片底部截止图标 + 日期 |
| 开始日期 | @start 2026-06-16 | 卡片底部开始图标 + 日期 |
| 重要等级 | @priority 4 或 @importance 4 | 1–5 星（淡黄色，满星填充） |
| 目标类型 | @goal complete / @goal risk | 目标看板：完成效果（淡蓝）/ 未完成后果（灰爆） |
| 颜色标签 | @labels red, blue 或 @label green | 明细页顶栏色条（权重 n）；列表页不显示 |
| 顶栏色 | @top red 或 @top orange | 明细页卡片顶部粗色条（Trello 顶栏） |
| 背景色 | @bg orange 或 @bg #FFE0B2 | 整卡背景色 |
| 顶栏色 | @top red 或 @top #E53935 | 卡片顶部色块（Trello 顶栏） |
| 勾选框 | - [ ] 未完成 / - [x] 已完成 | 卡片内 checklist |
预置标签色名
red · orange · yellow · green · blue · purple · pink · sky · lime · black
也支持 #RGB / #RRGGBB 十六进制。
描述正文
除 @ 指令与 checkbox 行以外的 Markdown（段落、列表、加粗等）→ 卡片描述区。
完整示例
# 待办
## 规则引擎文档
@due 2026-06-18
@labels blue, green
@top purple
- [ ] 编写 kanban-rules.js
- [ ] 补充映射说明
完成 **Markdown ↔ 看板** 双向转换说明。
# 进行中
## 看板 UI
@bg #FFF3E0
@top orange
@due 2026-06-20
- [x] Trello 列布局
- [ ] 拖拽交互
# 已完成
## 需求梳理
@labels green
- [x] 对齐 article / nanolog 结构编辑方式
| 状态 | 行为 |
|---|---|
| 锁定（默认） | 不可拖拽；隐藏 ReDeplog / Edit Post / 映射说明 |
| 解锁 | 仅在 week_start～week_end 窗口内可切换；可拖拽卡片跨列（本地预览） |
| 保存 | 点击 Edit Post：先将当前看板按映射规则序列化写入 content/kanban/_edit-buffer.md（缓冲），再覆盖 content/kanban/<周>.md；无 Token 时复制到剪贴板并在 Codeberg 编辑器粘贴 |
| 超期 | 截止日 week_end 当日 23:00（站点 zola.toml → extra.timezone）之后永久只读，无法解锁 |
列表页进度色
仅「待办 / 进行中 / 已完成」三列参与进度；「资源 / 目标」不参与。
背景色规则
| 条件 | 卡片背景 |
|---|---|
todo > 3 | 全红 #FFEBEE |
done == total 且 total > 0 | 浅绿 #E8F5E9 |
| 其余 | 按加权进度百分比渐变（红 → 黄 → 绿） |
加权进度公式
以 50% 为基准，逐卡片累加（标签数 n 为权重，无标签时 n = 1）：
| 所在列 | 单项贡献 |
|---|---|
| 待办 | −10% × n |
| 进行中 | +5% × n |
| 已完成 | +15% × n |
例：进行中列卡片有 2 个 @labels → +5% × 2 = +10%。
结果 clamp 至 0–100%，写入 front matter stats.progress_pct。
列表页标题显示 core_tasks（非日期）；元信息行含开始 / 截止 / 剩余天数 / 星级（importance 字段，1–5）。
相关文件
| 文件 | 作用 |
|---|---|
content/kanban/ | 看板 Markdown 唯一维护目录 |
static/js/kanban-rules.js | 解析 / 序列化规则引擎 |
static/js/kanban-board.js | 看板 UI、锁定、拖拽、Edit Post 缓冲写入 |
static/js/kanban-list.js | 列表页剩余天数、动态刷新进度 |
content/kanban/_edit-buffer.md | Edit Post 前的 Markdown 缓冲文件 |
templates/kanban.html | 周计划明细（Trello 风格） |
templates/kanban_list.html | 周计划列表 |
示例看板：content/kanban/2026-06-16.md