内容创作与风格指南¶

欢迎加入 CS for NCU 的内容创作团队！🎉 这份指南是我们共同维护项目质量、提升读者体验的基石，旨在帮助我们将个人的智慧，汇聚成一部风格统一、结构清晰、富有生命力的学习指北。同时为了方便写作者，我们提供一个 Prompt 来帮助你快速构建文档格式。

我们的核心理念

为学习者扫清障碍，为探索者点亮道路。

第一部分：基础书写规范¶

这是我们对专业排版最基本的尊重，也是保证内容可读性的前提。

1. 标点符号规范¶

核心原则：在中文语境下，所有标点符号都应使用全角（Full-width）字符。

详细规则与示例

为了更直观地对比，我们采用以下横向表格的形式呈现规则。

标点类型	正确用法 (✅)	错误用法 (❌)
句中标点	你好，世界。今天天气怎么样？	你好, 世界. 今天天气怎么样?
括号	这是一个示例（非常重要）。	这是一个示例(非常重要)。
顿号	我喜欢苹果、香蕉、和西瓜。	我喜欢苹果, 香蕉, 和西瓜。
引号与冒号	他曾说：“学无止境。”	他曾说:"学无止境."
引用内部为完整英文	他喊道：“Stop, right now!”	他喊道：“Stop， right now！”

2. 空格使用规范 (“盘古之白”)¶

核心原则：当中文与西文（英文、数字、符号）混合时，在它们之间增加一个半角空格。

详细规则与示例

规则类型	正确用法 (✅)	错误用法 (❌)
中文与英文之间	这个项目基于 React 框架。	这个项目基于React框架。
中文与数字之间	我在 2024 年购买了它。	我在2024年购买了它。
数字与单位之间	内存占用为 256 MB。	内存占用为 256MB。
中文与链接之间	请参考这份文档。	请参考这份文档。

3. Markdown 基础语法¶

核心原则：正确、一致地使用 Markdown 语法，构建逻辑清晰、结构严谨的文档。

查看基础语法速查表

类别	✅ 正确做法	❌ 错误做法
标题	`#` 后有空格，层级分明，不跳级。	`#标题`，随意跳级（如从 `##` 到 `####`）。
列表	`-` 或 `1.` 后有空格，嵌套正确缩进。	`-列表项`，缩进混乱。
代码	行内用 `，代码块用 ``` + 语言。	用引用 `>` 或加粗 `**` 展示代码。
链接	链接文本需有意义。`[MDN 文档](...)`	使用“点击这里”作为链接文本。
图片	`alt` 文本永远不为空，需有描述性。	`alt` 文本为空，如 `![](cat.png)`。
强调	`加粗` 用于强力强调，`斜体` 用于术语。	滥用加粗和斜体，用标题做强调。
段落	用一个空行来分段。	只用一个回车换行来分段。

第二部分：善用项目特性¶

我们启用了强大的 MkDocs 扩展，它们是你的“神兵利器” 🗡️，请在合适的场景下尽情使用。

1. 用 `admonition` (提示框) 赋予段落生命¶

不同的信息，需要不同的“语气”。提示框就是我们表达语气的最佳工具。提示框样例里面收录了所有本框架支持的提示框样式。

Admonition 用法示例

!!! reminder "这是一个标题"
    这里是提示框的内容，需要缩进四个空格。

    - 也可以包含列表。
    - 和其他 Markdown 元素。

??? danger "这是一个默认折叠的折叠框"
    这里是提示框的内容，需要缩进四个空格。

    - 也可以包含列表。
    - 和其他 Markdown 元素。

???+ danger "这是一个默认展开的折叠框"
    这里是提示框的内容，需要缩进四个空格。

    - 也可以包含列表。
    - 和其他 Markdown 元素。

自定义样式¶

这些是我们精心设计过的、具有独特视觉风格的提示框。

类型 (`!!! <type>`)	图标意象	核心用途
`danger`	龙 🐉	严重警告：用于描述不可逆的、有破坏性的操作或重大风险。
`alert`	克苏鲁 🐙	潜在陷阱：用于提醒用户注意可能导致非预期结果或错误的细节。
`declaration`	号角 🎺	重要宣告：用于发布官方定义、规则、原则或重要声明。
`example`	钥匙 🔑	最佳实践：提供一个清晰、可参考的正面例子或操作指引。
`reminder`	感叹号 ❗	友好提醒：用于强调关键点、备忘录或需要记住的重要信息。
`story`	书本 📖	背景故事：用于讲述一段个人经历、项目历史或补充性的背景信息。
`quote`	引号 💬	引用观点：用于直接引用他人的话、书籍或文章中的段落。
`author`	笔者/羽毛笔 ✍️	作者补充：用于作者发表一些题外话、个人见解或元评论。

官方默认样式¶

这些是 Material for MkDocs 的标准类型，我们没有对其进行特殊样式定制，它们会显示主题的默认外观。

类型 (`!!! <type>`)	图标意象	核心用途
`note`	铅笔 📝	中性信息：用于提供补充性的、不带强烈感情色彩的普通信息。
`info`	信息 ℹ️	参考信息：与 `note` 类似，同样用于提供一般性的参考资料。
`abstract`	摘要 📋	内容摘要：用于在文章开头提供“太长不看”(TL;DR) 版本或总结。
`tip`	灯泡 💡	实用技巧：提供建议、捷径或能提高效率的小窍门。
`success`	勾号 ✅	成功状态：表示一个操作已成功完成或一个问题得到了正确解决。
`question`	问号 ❓	提出问题：用于常见问题解答 (FAQ) 或引导读者思考某个问题。
`failure`	叉号 ❌	失败状态：明确指出一个错误、失败的操作或不推荐的做法。
`bug`	臭虫 🐞	报告缺陷：专门用于描述一个已知的软件缺陷或问题。

合理地使用这些提示框，会让你的文档结构分明，重点突出，极大提升读者的阅读体验。

2. 用 `tabbed` (标签页) 化繁为简¶

当信息存在多个“平行世界”（如不同操作系统、不同配置方案）时，使用标签页来组织它们。

Tabbed 用法示例

=== "Windows 操作系统"
    在 Windows 上，下载 `.exe` 安装包，双击运行即可。

=== "macOS 操作系统"
    在 macOS 上，我们推荐使用 Homebrew: `brew install a-cool-tool`

=== "Linux (Ubuntu) 操作系统"
    在 Linux 上，使用 `apt` 包管理器: `sudo apt install a-cool-tool`

Windows 操作系统macOS 操作系统Linux (Ubuntu) 操作系统

在 Windows 上，下载 .exe 安装包，双击运行即可。

在 macOS 上，我们推荐使用 Homebrew: brew install a-cool-tool

在 Linux 上，使用 apt 包管理器: sudo apt install a-cool-tool

好的，完全没问题。为这一部分添加介绍性文本，可以让协作者更好地理解这些高级功能的价值和用法。

下面是为您添加了介绍性文本后的 高级代码块特性 部分。我保持了您原有的结构和示例，只在其中穿插了解释性文字。

3. 高级代码块特性¶

标准的 Markdown 代码块足以展示代码，但通过 Material for MkDocs 启用的高级特性，我们可以将代码的呈现和解释提升到新的高度。这些功能对于编写技术教程、代码分析和文档至关重要。

带标题的代码块¶

为代码块添加一个标题（通常是文件名）可以立即为读者提供上下文。这对于展示配置文件、脚本或不同文件之间的交互尤为重要。

带命名代码块用法示例

```yaml title="config.yml"
site_name: My Docs
theme:
  name: material
```

带行号的代码块¶

在解释代码时，能够精确地引用特定行号会非常方便。使用 linenums 即可开启行号显示。你甚至可以指定起始行号（例如 linenums="10"），这在展示大文件片段时很有用。

带行号代码块用法示例

```python linenums="10"
def my_function():
    # 这行会从第 10 行开始编号
    print("Hello, World!")
```

使用高亮 (`hl_lines`) 的代码块¶

高亮特定代码行是引导读者注意力的最强工具。当你想让读者聚焦于某几行关键代码时，hl_lines 是你的不二之选。它可以高亮单行（hl_lines="4"）、一个范围（hl_lines="7-9"）或多组不连续的行（hl_lines="4 7-9"）。这些特性可以自由组合，以达到最佳的展示效果。

行号与高亮代码块用法示例

```python hl_lines="4 7-9" title="示例代码" linenums="1"
# 这是一个 Python 示例
def fib(n):
    # 第 4 行将被高亮
    if n < 2:
        return n
    # 第 7-9 行将被高亮
    result = fib(n-1) + fib(n-2)
    print(f"fib({n}) -> {result}")
    return result
```

效果展示¶

展示高亮
# 这是一个 Python 示例
def fib(n):
    # 第 4 行将被高亮，这是函数的基线条件
    if n < 2:
        return n
    # 第 7-9 行将被高亮，展示递归调用的核心逻辑
    result = fib(n-1) + fib(n-2)
    print(f"fib({n}) -> {result}")
    return result

第三部分：内容结构与协作¶

1. `tasklist` (任务列表) 追踪章节进度¶

对于正在撰写或规划中的章节，我们强烈推荐在章节导览页 (index.md) 的顶部使用任务列表来追踪进度。这能让所有协作者对本章状态一目了然。

Tasklist 用法示例

- [x] 已完成的任务
- [ ] 未完成的任务

确定指南核心原则
融合 MkDocs 插件特性
加入 Emoji 使用指导
收集社区反馈并持续迭代

2. `tags` (标签) 构建知识网络¶

标签是连接我们所有知识点的“神经网络” 🧠。一个好的标签系统能让读者进行“跳跃式”学习。

操作前请注意 ⚠️

在为一篇文章打标签前，请务必先访问网站的“标签索引”页面，查看已有的所有标签，尽量复用，避免创造相似意义的新标签。

示例 (01-self-help.md 的 Frontmatter):

Tasklist 用法示例

---
tags:
- 排错
- 思维方式
- 新手入门
---

3. `details` (可折叠内容) 保持页面清爽¶

对于非核心、但有必要提供的信息（如错误日志、大段代码），请用可折叠块将其“藏”起来。

Details (可折叠内容) 用法示例

??? example "这是一个默认折叠的标题"
    这里是需要被隐藏的内容。
    它可以包含任何 Markdown 元素，比如代码块：

    ```python
    print("Hello from a collapsible block!")
    ```

点击查看一份（虚构的）冗长错误日志

Traceback (most recent call last):
  File "/Users/cs4ncu/project/main.py", line 42, in <module>
    process_data(data)
  File "/Users/cs4ncu/project/utils.py", line 128, in process_data
    raise ValueError("Incompatible data format found.")
ValueError: Incompatible data format found.
... (此处省略 100 行) ...

第四部分：Emoji 使用的艺术¶

目前觉得就是别用 emoji，不用 emoji 的效果最好

第五部分：零散的细节¶

Admonition 里面的 list 上面一定要多空一行
标题里面表格里面尽量不用 ` 去写行内代码
重要的名词用英文解释一下，特别是看中文容易歧义的
注意俩个 ```` 可以用来包裹 ``` 而避免渲染错误，简而言之，就是使用外层比内层多一个反引号的规则，来确保 Markdown 渲染器能够正确地识别和显示嵌套的代码块。
还有 keys，image，grid，Icons，button，等等拓展的写法，有待更新。
为标题和小标题添加 ID。
图片放在文章所属 nav 的 assets 文件夹里面。

这份指南本身就是我们共同创作的第一份作品。让我们一起遵守它、完善它，用我们的智慧和热情 🙏，为南昌大学的学子们点亮一条清晰、温暖的计算机学习之路。