7. 参与维护

如何修正或扩展这个 Wiki。

快速修正（错别字、一句话）

1. 编辑 docs/ 下对应的 .md 文件。
2. 运行 ../.venv/bin/mkdocs build 重新生成 ../site/zh/ 下的静态站点，或运行 ../.venv/bin/mkdocs serve 实时预览。
3. 确认满意后提交。

这个 Wiki 只存在于本机：没有远程仓库、没有 CI、没有 Pages。阅读者可以本地打开 site/index.html，也可以自己运行 mkdocs serve。

本地开发（编辑时预览）

cd xly-wiki/zh
../.venv/bin/mkdocs serve         # http://127.0.0.1:8000，支持实时刷新

重新生成自动目录

python scripts/gen_catalog.py     # 通过 ~/.my.cnf 查询实时 DB，写入 docs/auto-catalog/**

脚本直接使用 ~/.my.cnf 的 [client] 配置连接实时 MySQL。需要时可用环境变量覆盖：

DB_DEFAULTS_FILE=/path/to/other.cnf python scripts/gen_catalog.py
DB_NAME=xlyweberp_some_other      python scripts/gen_catalog.py

生成器每次运行都会清空并重写 docs/auto-catalog/{tables,views,procedures,functions}/ 下的全部文件。这些目录中的手工修改会丢失。

Pre-commit hook（可选，建议本地编辑时使用）

安装一次：

ln -s ../../scripts/precommit.sh .git/hooks/pre-commit
chmod +x scripts/precommit.sh

hook 会在每次提交时运行 mkdocs build --strict，以便在提交前发现断开的交叉链接。

风格

• Markdown 源文件是事实来源。 site/ 中的静态 HTML 是生成物，不要手工编辑。
• 中文正文保留代码和业务术语的原始标识符。 术语翻译集中在 术语表。
• 切片是叙述的主要位置。 概念页和参考页保持短小；如果概念页超过约 300 字，通常应改成一个切片。
• 自动目录页不手工编辑。 从手写内容交叉链接到自动目录，不反向维护叙述。
• 多做交叉链接。 切片中首次提到框架表时应链接到自动目录，首次提到概念时应链接到概念页。

添加新切片

1. 创建 docs/slices/NN-<name>.md。
2. 把它加入 mkdocs.yml 的导航。
3. 端到端记录该切片（一个 UI 动作，贯穿所有层）。
4. 将概念链接到 Concepts，将表 / 存储过程链接到 Auto-Catalog。
5. 更新 切片索引 表。

添加新概念

只有当至少一个切片引入该概念时才添加概念页。没有任何引用的概念页是负担。