看板 Markdown 映射说明

周计划看板 · Markdown 映射说明

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

文件命名

文件名同时是「生成并复制到剪贴板 / 同步到仓库」时提示的目标文件名（新建时按上面的规则生成，时分取自打开 GUI 编辑器的那一刻，编辑过程中不再变化）。

URL 唯一性（重要）：Zola 会把文件名开头的 YYYY-MM-DD 当成页面日期并从 slug 中剥离，只剩余下部分参与 URL。因此每块看板都在 front matter 里显式写 slug（= URL 安全化的文件名），否则会出现两类事故：不同日期的同一时段撞车（2026-08-11_晚上.md 与 2026-10-13_晚上.md 都会变成 /kanban/wan-shang/，构建报 Found path collisions）；多天与单日「全天」也会混淆。GUI 新建 / 编辑时都会自动写入 slug。

因为多天看板的文件名带上了结束日期与创建时分，多天、全天、上午、下午、晚上这五类看板可以在同一天共存，且 URL 各自唯一。

历史文件：2026-06/07 创建的 4 块多天看板已统一迁移为新命名（2026-06-16-06-22-0934.md 等）， 并在 front matter 里加了 slug（新 URL）与 aliases（旧 URL），老链接照常可访问； 用 GUI 修改这些看板并保存时，slug 与 aliases 都会被保留。

编辑时的锁定规则

修改已有看板时不会重命名文件、也不会改写已有 slug，因此 URL 保持稳定。

新建时的重复提示

新建看板时，如果所选时间段与已有看板重叠，编辑面板会直接提示：

• 完全相同（起止一致）→ 「该时间段已有看板：<核心任务>（起 ~ 止），建议到列表里点它的「✎ 编辑」修改，而不是新建。」
  
• 部分重叠 → 「该时间段与已有看板重叠：<核心任务>（起 ~ 止），继续新建会同时存在两块时间重叠的看板。」

提示数据来自列表页内嵌的看板清单，随你调整起止日期实时更新；修改已有看板时不会出现该提示。

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

单日看板（带时段）额外写一行 slug，GUI 新建 / 编辑时会自动带上：

+++
title = "2026-10-13 晚上 计划"
date = 2026-10-13
slug = "2026-10-13-wan-shang"
template = "kanban.html"
[extra]
week_start = "2026-10-13"
week_end = "2026-10-13"
period = "晚上"
+++

结构映射

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

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

卡片属性 · 规则引擎指令

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

预置标签色名

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