处世如大梦，悟者能有几

— 宋·李纲

这套博客方案基于 Fossil 原生能力 构建，目标是：

  • 首页自动按分类展示文章列表
  • 文章内容直接使用 Markdown（/doc/tip/... 渲染）
  • 风格简洁、中文友好、便于个人长期维护

一、目录结构约定

请按以下结构组织内容：

docs/
  _meta/
    site.json
  _index.tsv
  _home.md
  about.md
  数值方法/
    示例文章.md
  Python科学计算及编程/
    示例文章.md

说明：

  • docs/<分类>/：你的文章目录，分类名就是文件夹名
  • docs/_index.tsv：自动生成的文章索引（不要手改）
  • docs/_home.md：自动生成的首页内容（不要手改）
  • docs/_meta/site.json：站点元信息（标题、作者等）

二、首次接入（给自己或其他人）

  1. 克隆或打开 Fossil 仓库
  2. 确保仓库内包含：
    • tools/build_index.py
    • tools/build_home.py
    • tools/pre_commit_refresh.sh
    • skin/header.tmpl
    • skin/footer.tmpl
    • skin/style.css
  3. 启用提交前钩子（仅首次）
chmod +x tools/pre_commit_refresh.sh
fossil hook add --type before-commit --command "./tools/pre_commit_refresh.sh" --sequence 50
  1. 设置首页入口（仅首次）
fossil sql --repository ../Fossil-Blog.fossil \
  "update config set value='/doc/tip/docs/_home.md', mtime=strftime('%s','now') where name='index-page';"
  1. 导入皮肤配置（仅首次，管理员执行）
fossil configuration push skin
fossil configuration push project

三、日常写作流程（最简）

你只需要：

  1. 在 docs/<分类>/ 新增或修改 .md 文章
  2. 执行提交：
fossil commit -m "更新文章"

提交前钩子会自动执行：

  • 生成 docs/_index.tsv
  • 生成 docs/_home.md
  • 自动把生成文件加入本次提交

四、文章写作建议

每篇文章建议以一级标题开头，索引会提取第一个 # 作为文章标题：

# 牛顿迭代法入门

作者：你的名字  
更新时间：2026-04-15

若未写一级标题，则回退为文件名作为显示标题。

五、给其他人复用这套皮肤

其他人要复用时，推荐按以下顺序：

  1. Fork/Clone 仓库
  2. 修改 docs/_meta/site.json（站点标题、作者）
  3. 修改 skin/header.tmpl（主标题、署名）
  4. 新建自己的分类目录和文章
  5. 按“首次接入”启用 hook 与配置推送

只要目录结构一致，就能直接复用自动分类与首页生成能力。

六、常见问题

1) 本地更新了，远端没变

  • 先执行：fossil sync
  • 再确认配置是否已推送：fossil configuration push skin / project

2) 首页报 Not Found

  • 检查 index-page 是否为：/doc/tip/docs/_home.md

3) 作者显示两次

  • 作者应仅保留在 skin/header.tmpl
  • docs/_home.md 不要再写作者行

七、快速自检命令

fossil hook list
fossil info
fossil timeline -n 5 -t ci

如果以上正常，这套皮肤即可长期稳定使用。