本 wiki 写作规范
本 wiki 用 Zensical（MkDocs Material 兼容）渲染，同一份 markdown 同时发布成给人看的 HTML 和给 AI 读的 .md 源。往这里写任何东西都先读完这一页。本页和子 skill 里的「活例」默认不点开：规矩本身写到能照做，拿不准哪一条时才点开那一条的活例。
写作流程
- 按七问定板块和位置
- 写正文，顶部写一行
description - 在
mkdocs.yml的nav:注册 - 在某个祖先目录的索引页（
index.md/SKILL.md）挂一行带钩子的链接 —— nav 只给人看，AI 只顺相对链接走，没挂上的页面对 AI 等于不存在 - 跑
python3 scripts/check-links.py，不过就改完再跑；deploy.sh构建前也跑，不过不许部署 - 到这里为止：commit、push、部署都等用户说。渲染效果（含 mermaid）由用户自己在浏览器里看，AI 不截图 —— 有 mermaid 的页面提醒一句，原因见 mermaid 的坑
内容放哪个板块
顶层七个板块：笔记、Gallery、文章、项目排在一根从通用到具体的轴上，Skills 是这根轴的背面，收藏夹和维护在轴外 —— 为什么这样分见板块怎么分。主题只做板块内的二级目录。下面七问定的是一页放哪。收外面的东西先读收纳：先分诊，再照每一面的执行页收。按顺序问：
- 外面的整个来源 —— 一个论坛、一个人、一个合集，或者拿来就用的工具站 —— 只存一个链接加一句为什么收？→ 收藏夹，按来源的形态进
bookmarks/下的分类页，一条一行，写法见一条怎么写。单篇帖子、文章不进收藏夹；要从里面拆出一样写成页面，就按下面几问进轴，再回条目上补「拆出过」 - 一件现成的东西，通用到不用提问题就能挑 —— 一张图配 prompt、一段版式、一套配色、一种前端风格配 demo、一个人设？→ Gallery，目录是
gallery/，七类各一个子目录：images（图片）、layouts（排版）、colors（色彩）、video（视频）、audio（音频）、web（前端特效）、personas（人设，一人一页，定妆照加基本资料，活例 SEOA｜徐星澄）。本站自己做的，成品和做法写在同一页（花卉动态生长海报）；别人的照收进 Gallery。layouts 区的五个分类页和 colors 区的经典主题色页由scripts/build-handdraw-gallery.py从images/handdraw-style/assets/生成，别手改；两区的index.md手写 - 给 agent 照着做的执行方式 —— 某一层的 AI 影子，只留一种做法，守则加脚本？→ Skills
- 一个 skill、Gallery 收录或项目背后的事 —— 从哪来、为什么这么选、改过什么、实测过什么？→ 维护。skill 页只写怎么用，页尾链过来，写法见写 skill · 页尾链到维护记录；记录写什么见收纳的维护记录
- 一个具体的东西 —— 自己做的软件、别人的仓库，讲它解了哪些问题，每个问题只留它那一种方案？→ 项目，一个项目一个目录，按领域进分组，自己做的、拆别人的都算。讲多深都算：粗讲一页，只讲它是什么、主路径怎么跑通；细讲一组，每个问题贴它的源码片段、讲架构、给实跑效果。粗讲要细讲时在同一个目录里长，入口地址不变；项目索引的钩子标明粗讲还是细讲。只为这个项目写的操作手册、截图跟着项目放，不单独算 skill —— 活例：Kindle 常显信息屏的越狱实操。拆别人的项目照调研项目粗讲、细讲，或写书的从零复刻、做实验
- 为了学会一门学问，读完能自己往下推 —— 算法、统计、机器学习、编程语言的学习、推导、题解？→ 笔记。可以给自己出题：写一个
```conflict块，上半是问、下半留空，python3 scripts/course.py status列出还空着的题，写法见提问块 -
其余：一个通用问题 —— 定义问题，给几种方案和依据，讲各自适合什么、怎么选，像一篇论文；可以贴代码，但只是示意，换个项目照样成立；选型、横向对照几个项目怎么解同一个问题、论文笔记也算 → 文章
-
能用在任意成品上的方法归 skill，只做一种成品的做法写在 Gallery 那页，只写本站经手过的，上游仓库里已有的指过去 —— 花卉动态生长海报的五步只做这一种海报，写在成品页；图片提示词反推 · 七维拆解是 skill，它整理的合集进了 Gallery，两边互链
- 正面和影子单向链：文章、项目、Gallery 讲原因，沉淀出的可复用手册是它的影子，归 Skills；正面页挂一行链到影子，skill 不链回去讲原理、背景和实现 —— skill 是给 AI 照着做的，为什么这样做它用不上。拿正面页当写法活例、指过去的不算。活例：动画网页 PPT链到它的工程手册，手册不链回来
- 归属变了就把文件真的搬过去，按下一节「挪文件」办
硬规矩
- 挪文件不留存根页：要保住旧 URL 就别挪；挪了就删原文件、站内引用一并改，
mkdocs.yml的redirects加一行兜站外书签（只管 HTML，旧.md地址照样 404）。存根页没人链、不进 nav，留着只会逼 check-links 开豁免口子 - 引外部一手资料三步：① 真身存档进
assets/，注明出处和获取日期，正文用??? abstract折叠 +--8<--展示；② 正文用>摘关键原句；③ 每处引用跟自己的分析。活跃开源仓库、关键契约已经消化成自己的话的，可以用钉 commit 的 GitHub 永链代替存档 —— 活例：Dashboard 的蓝本吸收 - 正文链接只指站内，外部来源进脚注：正文留
[^名]，URL 和读取日期写进文末脚注 —— 活例：对象存储部署。收藏夹的条目和极简收的那句「使用 xxx 仓库即可」除外：链接本身就是收的内容，直接写在句子上 - 代码即引用：展示仓库里的文件用
--8<--引真身，不复制粘贴；路径先相对docs/、再相对仓库根（skills/.../x.css、mkdocs.yml）。完整文件不单独成页，在讲它的页面文末??? abstract折叠引用 - 缩进 4 空格：折叠块、选项卡、提示框的子内容不缩 4 格就不被识别；代码块内部的缩进照原样
- 代码块语言标识写
python，不写py - 保留名：
reference、assets、scripts不能当.md文件名 —— 跟同级目录撞 URL，内容被静默丢弃 - check-links 豁免写在文件前 5 行：
<!-- link-check-ok: 为什么这篇不该上链路 -->。「已迁移存根」不算理由
每页一行 description
frontmatter 写一句话，进 HTML 的 <meta name="description">：
- 直接抄父级索引给它的那行钩子，两处说法一致
- 值用双引号包起来；不写 markdown 标记，
**和反引号在 meta 里会原样露出来
改不了的文件：目录级 .meta.yml
两类文件不塞 frontmatter：上游原文照录的存档（改了就不是原文），和被 --8<-- 引用的真身（frontmatter 会漏进引用它的正文）。在目录里放 .meta.yml，给该目录及子目录的页面当默认，页面自己写的优先：
docs/gallery/images/gpt-image2/.meta.yml
description: "GPT Image 2 图库（收录自 wuyoscar/GPT-Image2-Skill，MIT），整页中译，只改图片路径；来源与译法见维护记录 maintenance/gallery/gpt-image2.md"
一个目录一句话，写这批文件是什么、从哪来。
什么场景用什么语法
Material / pymdownx 的语法照常写，这张表只提醒什么时候该用上：
| 场景 | 用 |
|---|---|
| 同一件事有 Python / R 等几种写法 | 选项卡 === "Python" |
| 内容长、不是必读 | 折叠 ??? note "标题"，要默认展开写 ???+ |
| 易犯的错 / 操作建议 / 补充说明 | 提示框 !!! warning / !!! tip / !!! note |
| 代码里某几处要单独解释 | 代码注解：行尾写 # (1)，代码块后接编号列表 |
| 代码里要突出几行 | hl_lines="2-4" |
| 架构、流程、时序 | ```mermaid，有坑，见 mermaid 的坑 |
| 数据图表 | ```echarts，fence 里写 ECharts option |
| 公式 | $...$ / $$...$$ |
| 外部来源 | 脚注 [^名] |
| 读者要看到 JS 跑出来的结果 | ```{.js .run} → 可运行 JS 代码块 |
| 交互演示 | iframe 嵌自包含单页 → 嵌入交互单页 |
| 放图片、视频 | 按怎么看来排：单张用 <figure markdown> 居中；要对照着看的几张（首尾帧、改前改后）放进 <div class="grid" markdown> 并排，一张一个 figure 配 <figcaption>。别把几张塞进同一个 figure，主题把 figure 里的图设成块级，会上下摞成一长条。一组同类照片当图库翻的（姿势参考这类），放进 <div class="gallery-grid" markdown> 排三栏，每张写成 { loading=lazy } → 活例 ins风拍照姿势。正文里的图点了都弹灯箱放大，别再给图套指向它自己的链接，套了链接的图点了会直接跳走。动图效果放静音循环的 mp4，<video autoplay loop muted playsinline>，src 写站点根绝对路径，不放 GIF（体积是 mp4 的好几倍）→ 活例 花卉动态生长海报 |
| 不想公开的小字：服务器地址、域名、用户名 | `age:…` 打码 → 打码 |
| 一串按时间排的事件 | zx-timeline 块 → 时间线 |
| 读者要看、粘进对话框会被误读的内容 | zx-no-copy 块 → 复制时跳过 |
| prompt 按读者的选择走不同分支；可选的空没填就整行不要 | data-when 块 → 分支 |
| prompt 里要读者先填的空 | 单行 <input>、多行 <textarea>、选项 <select> 写进句子，带 placeholder，复制时换成填的值 → 填空 |
| AI 新生成的配图 | 手绘信息图 → 配图 |
critic 扩展（{==高亮==}）没开，别用。
文风
AI 代笔时照此写：
- 先结论后展开：段落第一句就是论点；标题直接说结论（「nav 随便重排，链接图纹丝不动」，不是「关于 nav 的说明」）
- 短句，破折号接推理：一句话说一件事；因果和转折用「——」接在句内，不起「因此 / 然而 / 值得注意的是」的套话头
- 要点一行一条：每条是可直接执行的指令或可检验的判断，不写「小标题：多行解释」的两段式
- 加粗只给结论和硬规矩，不给气氛词；形容词能删则删
- 技术词允许保留英文原形（commit、nav、snippet、iframe），叙述用中文，不音译不生造
- 规矩必须带活例：立一条规范就指一个站内真实例子，只指一个，挑最小、最贴的；规矩本身写到不点开活例也能照做。没有活例的规矩先别写
针对具体场景：
以下场景只有用户明确要求写作某个部分，或者进行精简检查才读：