Wiki 写法说明¶

本文档面向贡献者，介绍本 Wiki 所使用的 MkDocs Material 主题的 Markdown 写法规范，帮助你快速上手编辑文档。

基础标题¶

标题用于组织页面结构，同时也会出现在右侧目录导航中。

# 一级标题（页面标题，每个 .md 文件只有一个）
## 二级标题（章节，会出现在右侧目录）
### 三级标题（小节，也会出现在右侧目录）
#### 四级标题（段落小标题，不出现在目录中）

注意： 本站目录深度设置为 toc_depth: 2，即 ## 和 ### 级别的标题会显示在右侧目录导航中。如果你希望某个章节作为独立子目录显示，请使用 ##。

提示框（Admonition）¶

提示框用于突出重要信息，支持多种类型。写法为 !!! 加类型名，后面跟可选的标题。

注意 / 警告¶

!!! warning "注意"
    这是一条警告信息。

!!! danger "危险"
    这是一条危险操作提示。

注意

这是一条警告信息。

危险

这是一条危险操作提示。

提示 / 信息¶

!!! tip
    这是一条提示信息。

!!! tip "小贴士"
    这是一条实用小贴士。

Tip

这是一条提示信息。

小贴士

这是一条实用小贴士。

成功 / 失败¶

!!! success "成功"
    操作成功时的提示。

!!! failure "失败"
    操作失败时的提示。

!!! bug "已知问题"
    这是一个已知的问题。

成功

操作成功时的提示。

失败

操作失败时的提示。

已知问题

这是一个已知的问题。

可折叠提示框¶

使用 ??? 替代 !!! 可以创建默认折叠的提示框，使用 ???+ 则默认展开。

??? "点击展开详情"
    折叠起来的详细内容。

???+ "默认展开"
    默认就是展开状态的详细内容。

点击展开详情

折叠起来的详细内容。

默认展开

默认就是展开状态的详细内容。

引用块¶

引用块用于补充说明或引用重要信息，在本站中会显示为左侧金色边框的区块。

> **任务主线：** 这是一条引用说明。
>
> 引用块支持多行内容，空行用 `>` 连接。

任务主线： 这是一条引用说明。

引用块支持多行内容，空行用 > 连接。

表格¶

表格使用标准 Markdown 语法，用 | 分隔列，用 --- 分隔表头和内容。

基础表格¶

| 列1 | 列2 | 列3 |
| --- | --- | --- |
| 内容1 | 内容2 | 内容3 |
| 内容4 | 内容5 | 内容6 |

列1	列2	列3
内容1	内容2	内容3
内容4	内容5	内容6

表格内加粗¶

| 装备名称 | 获取地点 |
| --- | --- |
| **锈蚀黑剑** | 阴暗墓穴获取 |
| **凯瑟里克的盔甲** | 击杀凯瑟里克·索姆 |

装备名称	获取地点
锈蚀黑剑	阴暗墓穴获取
凯瑟里克的盔甲	击杀凯瑟里克·索姆

对齐方式¶

| 左对齐 | 居中对齐 | 右对齐 |
| --- | --- | --- |
| 内容 | 内容 | 内容 |

左对齐	居中对齐	右对齐
内容	内容	内容

列表¶

无序列表¶

- 项目一
- 项目二
- 项目三

项目一
项目二
项目三

有序列表¶

1. 第一步
2. 第二步
3. 第三步

第一步
第二步
第三步

加粗列表项¶

- **粗体项目：** 后面跟描述内容
- **另一个项目：** 描述内容

粗体项目： 后面跟描述内容
另一个项目： 描述内容

文字样式¶

**加粗文字**
*斜体文字*
~~删除线文字~~
`行内代码`

加粗文字 斜体文字 ~~删除线文字~~ 行内代码

代码块（语法高亮）¶

使用三个反引号包裹代码块，在开头反引号后加上语言名称即可启用语法高亮。

Markdown 代码示例¶

    ```markdown
    # 这是一级标题
    ## 这是二级标题

    - 列表项1
    - 列表项2

    | 表头1 | 表头2 |
    | --- | --- |
    | 内容1 | 内容2 |
    ```

CSS 代码示例¶

    ```css
    .md-typeset h1 {
        color: #ffc107;
        border-bottom: 2px solid #ffc107;
    }
    ```

YAML 配置示例¶

    ```yaml
    nav:
      - 首页: index.md
      - 装备攻略: ch8-equip.md
    ```

其他常用语言标识¶

语言	标识	适用场景
Markdown	`markdown`	Markdown 语法示例
CSS	`css`	样式代码
YAML	`yaml`	配置文件
Python	`python`	Python 脚本
JavaScript	`javascript` / `js`	JS 代码
Bash / Shell	`bash` / `sh`	命令行脚本
PowerShell	`powershell`	PowerShell 脚本
JSON	`json`	JSON 数据
HTML	`html`	HTML 代码
C#	`csharp` / `cs`	C# 代码
Lua	`lua`	Lua 脚本

提示： 如果不加语言标识，代码块会显示为普通文本，没有语法高亮和行号复制功能。

分隔线¶

使用三个短横线 --- 来创建分隔线，常用于分隔不同章节的内容。

---

修改主题颜色¶

本站的主题颜色在 docs/stylesheets/extra.css 中定义，使用金色（#ffc107）作为主色调。

修改主色调¶

如果你想更换颜色，修改 extra.css 中的以下变量：

:root {
    --md-primary-fg-color: #ffc107;       /* 主色 */
    --md-primary-fg-color--light: #ffe082; /* 浅色变体 */
    --md-primary-fg-color--dark: #ff8f00;  /* 深色变体 */
    --md-accent-fg-color: #ffc107;        /* 强调色 */
}

常用配色参考：

颜色	色值	效果
金色（当前）	`#ffc107`	暖色调，适合游戏攻略
翠绿	`#4caf50`	自然清新风格
天蓝	`#2196f3`	科技感风格
紫色	`#9c27b0`	神秘魔幻风格
红色	`#f44336`	热血战斗风格

修改标题栏渐变¶

.md-header {
    background: linear-gradient(90deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%) !important;
}

将三个颜色值替换为你想要的渐变色即可。

修改各级标题颜色¶

.md-typeset h1 { color: #ffc107; }  /* 一级标题 */
.md-typeset h2 { color: #ffe082; }  /* 二级标题 */
.md-typeset h3 { color: #ffd54f; }  /* 三级标题 */

新建页面¶

1. 创建 .md 文件¶

在 docs/ 目录下创建新的 .md 文件，文件名遵循 ch*-xxx.md 的命名规范。

2. 注册到导航¶

在根目录的 mkdocs.yml 文件中的 nav 部分添加新条目：

nav:
  - 首页: index.md
  - 新手入门: ch1-start.md
  - 你的新页面: ch13-yourpage.md   # 在这里添加

3. 本地预览¶

pip install mkdocs-material
mkdocs serve

浏览器打开 http://127.0.0.1:8000 即可预览。

常见问题¶

表格显示异常？¶

确保表头分隔行 | --- | --- | 的短横线数量至少为 3 个，且每列都有分隔符。

提示框不生效？¶

确保 mkdocs.yml 中已启用 admonition 扩展（本站已启用）：

markdown_extensions:
  - admonition
  - pymdownx.details

修改后页面没变化？¶

GitHub Actions 自动部署通常需要 1-2 分钟。如果超过 5 分钟仍未更新，请检查 Actions 页面的构建状态。