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