看板 Markdown 映射说明

周计划看板 · Markdown 映射说明

看板数据统一存放在 content/kanban/（一个 .md 文件 = 一个自然周，或单日「上午 / 下午 / 晚上」时段看板）。
Zola 构建时将原始 Markdown 内嵌到页面，规则引擎直接解析，无需 static/ 副本。

文件命名

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 }
+++

结构映射

列顺序 = 文件中 # 出现顺序。
卡片顺序 = 各列内 ## 出现顺序。

列表级可选指令（写在 # 列名 之后、第一张卡片之前）：

卡片属性 · 规则引擎指令

指令单独占一行，写在 ## 标题 之后、正文之前。以 @ 开头，大小写不敏感。

预置标签色名

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 结构

编辑方式

看板详情页（Trello 对齐）

明细页 UI 全盘参考 Trello 重构：

以上所有本地修改都会提示“有未保存的本地修改”，统一通过 Edit Post 序列化保存。

GUI 编辑器（新建 / 修改看板）

除了直接编写 Markdown，看板提供 GUI 方式生成 / 修改：按「看板图标 / 指令的可选值」用下拉框或手动输入设置，自动生成 Markdown。

布局（Trello 风格：画布 + 检查器）

• 左侧画布：实时渲染当前看板（背景、列、卡片封面/标签/徽标），点击列或卡片即可选中编辑；底部/右侧可「添加列表」「添加卡片」。
• 右侧检查器：根据选中对象切换编辑面板：
  • 未选中（看板）：周起止（顶格时间：先设置；1–14 天；新建默认今日；修改时开始锁定） / 时段 period（单天唯一性） / 核心任务 / 标题 / 描述 / 星级 / 收藏 / 看板背景色板；
  • 选中列表：列名 / @sort 排序 / @sort-order 方向 / 添加卡片 / 上移下移 / 删除列 / 卡片列表；
  • 选中卡片：标题 / 开始 / 截止（新建时默认按创建时间=今日填充，可编辑但限制在周起止区间内）/ 优先级 / 目标 / 封面（@bg + @cover）/ 顶栏色 / 标签 / 完成 @done / 置顶 @pin / 勾选清单 / 描述。
• Markdown 预览：底部可折叠，输入时实时更新。

入口

字段与指令对应（每个“图标“的可选值）

默认新建布局

待办    进行中    已完成    进度        ← 主流程列（竖向一排）
资源    目标                             ← 底部并排一行

• 进度列：从 week_start 到 week_end 每一天生成一张卡片（标题如 07-13 周一），每张默认含一条勾选清单「记录当日完成内容」（可勾选 / 划线）；
• 修改顶格时间且进度列仍为自动生成样式（标题匹配 MM-DD 周X）时，编辑器会自动重排天数；
• 置顶：置顶卡片始终显示在同列表顶部（多个可同时置顶），卡片正面带 📌 徽标；解锁模式下每张卡片都有「📌 置顶 / 📌 置顶中」切换按钮，点击即置顶/取消置顶；GUI 编辑器卡片面板同样提供按钮。

生成 → 剪贴板 → 创建 / 修改流程

1. 填写表单，右侧 Markdown 预览实时更新（也可点「仅复制 Markdown」）。
2. 点 生成并复制到剪贴板：
   • 自动将序列化后的 Markdown 复制到剪贴板；
   • 弹出操作流程提示，明确区分 创建 还是 修改：
     • 创建（content/kanban/<周>.md 不存在）：打开 Codeberg 新建文件 → 粘贴 → 保存提交 → ReDeplog 部署 → 刷新列表；
     • 修改（文件已存在 / 编辑已有看板）：打开 Codeberg 覆盖文件 → 全选替换 → 保存提交 → ReDeplog 部署 → 刷新列表。
3. 若浏览器已保存 kanbanToken，可点 用 Token 直接同步到仓库（文件不存在走 POST 创建，存在走 PUT 覆盖），再打开 ReDeplog 部署。

相关文件

列表页进度色

仅「待办 / 进行中 / 已完成」三列参与进度；「资源 / 目标」不参与。

背景色规则

加权进度公式

以 50% 为基准，逐卡片累加（标签数 n 为权重，无标签时 n = 1）：

例：进行中列卡片有 2 个 @labels → +5% × 2 = +10%。

结果 clamp 至 0–100%，写入 front matter stats.progress_pct。

列表页标题显示 core_tasks（非日期）；元信息行含开始 / 截止 / 剩余天数 / 星级（importance 字段，1–5）。

相关文件

示例看板：content/kanban/2026-06-16.md