跳转至

信息框与补充内容规范

信息框与补充内容规范

本页讨论的不是 MkDocs 信息框的语法本身，而是它们在 Physics Learning Wiki 里应该承担什么职责。语法细节仍以 格式手册 为准；本页更关心的是：什么信息该不该放进信息框，应该用哪一类信息框，以及应该放在正文的什么位置。

核心原则

  1. 信息框是为了帮助阅读，而不是为了增加页面的视觉变化。
  2. 正文主线不应被大量信息框切碎；核心定义、核心定律和主推导应尽量留在正文里。
  3. 只有当一段内容具有明确的“信息类型”时，才应该放进信息框，例如注意事项、例题、补充推导、方法建议和编辑说明。
  4. 同一页面中应尽量复用少量固定类型，不要今天用 warning、明天用 danger、后天再换 info，导致读者无法形成稳定预期。

???、???+ 与 !!! 的分工

???

默认折叠。适合放入第一次阅读时可以暂时跳过的内容，例如：

  • 拓展示例。
  • 补充推导。
  • 历史背景。
  • 术语补充说明。

???+

默认展开。适合放入对当前阅读确实重要、但又希望用块状形式强调的信息，例如：

  • 容易导致概念性误解的注意事项。
  • 与当前段落紧密相关的例题。
  • 阅读本节前必须知道的符号约定或适用条件。

!!!

始终展开，且不具备折叠功能。除非一段提示非常短且必须始终可见，否则一般内容页优先使用 ??? 或 ???+。在 Physics Learning Wiki 中，!!! 更适合很短的站点级提示，而不适合承载长篇补充内容。

推荐保留的几类信息框

为保持全站一致性，普通物理内容页建议优先使用下列几类：

note

最常用、最中性的类型。适合放：

  • 说明。
  • 例题。
  • 推导。
  • 补充讨论。
  • 术语、历史或阅读建议。

推荐标题：说明、例题、推导、补充、术语说明。

warning

只用于真正容易误导读者的内容，而不是把所有提示都染成黄色。适合放：

  • 符号与正负号约定。
  • 模型适用条件。
  • 常见概念混淆。
  • 很容易被误用的近似前提。

推荐标题：注意、易错点、边界条件。

tip

适合放学习方法、建模建议和阅读建议，而不是物理结论本身。适合放：

  • 解题建议。
  • 阅读路径建议。
  • 投稿与写作建议。

推荐标题：方法、建议、阅读提示。

success 与 failure

这两类主要用于规范页面本身，用来展示“推荐写法”和“不推荐写法”。普通物理内容页一般不建议滥用它们。

信息类型与推荐放置位置

信息类型推荐写法推荐位置说明
页面状态说明??? note "说明"页面开头概述前后均可例如“本页仍在完善中”。这类内容通常不应使用 warning。
前置知识提醒正文一行或 ???+ tip "阅读提示"页面开头如果对理解主线非常关键，优先直接写在正文中。
例题???+ note "例题：……"对应概念或定律之后如果例题是主线的一部分，应默认展开。
拓展示例??? note "拓展示例：……"主线例题之后第一次阅读可以跳过。
补充推导??? note "推导"结论之后核心推导不要全部藏进折叠框。
易错点???+ warning "易错点"相关概念或例题之后应就近放置，不要堆到页面最后。
模型条件???+ warning "注意"公式或模型首次出现处尤其适合说明近似条件、适用范围和符号约定。
学习方法??? tip "方法"例题或小节结尾例如“先画受力图再列方程”。
编辑流程说明??? note "投稿说明" 或正文贡献、格式或编辑入口页不应混入普通学科正文页。

常见模板

页面状态说明

1
2
??? note "说明"
    本页内容仍在持续完善中，欢迎大家提出建议和补充。

关键注意事项

1
2
???+ warning "注意"
    本节中的功统一按“系统对外做功为正”记号书写。若使用其他约定，后续公式的符号需要整体调整。

主线例题

1
2
???+ note "例题：绝热压缩中的温度变化"
    先明确系统边界和过程条件，再决定使用状态方程还是能量关系。

可跳过的补充推导

1
2
??? note "推导"
    如果你只想先掌握结论，可以先跳过这一段推导，读完主线后再回来看。

普通内容页的推荐组合

对于大多数正文页，通常只需要以下三类就够了：

  1. note：放例题、补充说明和可跳过推导。
  2. warning：放易错点、适用条件和关键约定。
  3. tip：放学习方法和阅读建议。

如果一页出现了太多不同颜色和样式的信息框，通常说明页面结构本身已经需要调整。

不推荐的用法

  1. 把整页所有补充信息都写成 warning。
  2. 把核心定义、核心结论和主推导全部藏进默认折叠的框里。
  3. 用信息框替代正常的小节结构。
  4. 在学科正文中放入编辑流程、待办事项或面向贡献者的备注。
  5. 为了“看起来丰富”而无差别使用 danger、bug、example 等稀有类型。

一个简单判断标准

当你准备插入信息框时，先问自己三件事：

  1. 这段内容是主线正文，还是补充信息。
  2. 它是在提醒读者小心，还是在给读者补充例子与方法。
  3. 第一次阅读时，这段内容是否必须立即看见。

如果答案分别是“补充信息”“补充例子”和“不是必须立刻看见”，那通常就应该使用 ??? note；如果答案是“容易误导读者”“必须立即看见”，才更接近 ???+ warning。

与其他规范的关系

  • 语法和缩进规则见 格式手册。
  • 页面叙事、例题写法和 Why 推进见 内容编写指引。
  • 各学科更具体的用法，应再参考对应模块的章节编写说明。
本页面最近更新：2026/3/8 09:28:31，更新历史
发现错误？想一起完善？ 在 GitHub 上编辑此页！
本页面贡献者：Leafuke, Physics Learning Wiki
本页面的全部内容在 CC BY-SA 4.0 和 SATA 协议之条款下提供，附加条款亦可能应用

评论