Markdown 使用说明

Markdown 使用说明¶

本文档说明本项目中 Markdown 的适用场景、支持的语法及 Mermaid 流程图用法，供后台编辑与前台作者参考。

一、适用场景¶

以下内容支持 Markdown 渲染（需在后台或编辑时勾选「使用 Markdown」或默认启用）：

场景	说明
产品详情	产品「详细介绍」正文，后台产品编辑中勾选「使用 Markdown」后生效。
新闻详情	新闻正文，后台新闻编辑中勾选「使用 Markdown」后生效。
社区帖子	帖子正文与回复内容，发帖/回复时默认使用 Markdown；另支持 `<img src="/static/expression/id.gif" alt="" class="inline-block align-middle expression-emoji">` 表情语法。
关于我们	公司简介等配置内容，后台「关于页」中勾选「使用 Markdown」后生效。

二、基础语法¶

2.1 标题¶

# 一级标题
## 二级标题
### 三级标题
#### 四级标题

2.2 强调与行内代码¶

**粗体** 与 *斜体*，以及 `行内代码`。

2.3 列表¶

- 无序列表项一
- 无序列表项二

1. 有序列表第一项
2. 有序列表第二项

2.4 链接与图片¶

[链接文字](https://example.com)
![图片替代文字](图片地址)

2.5 引用¶

> 这是一段引用内容。

2.6 换行¶

单个换行在 Markdown 中会转成 <br>，无需在行尾加两个空格。
空一行表示新段落。

三、代码块¶

使用围栏式代码块，并建议写上语言标识以便语法高亮：

```python
def hello():
    print("Hello, World!")


常用语言标识示例：`python`、`javascript`、`html`、`css`、`bash`、`json`、`text` 等。前台会使用 highlight.js 对代码块进行高亮。

---

## 四、表格

```markdown
| 列一   | 列二   | 列三   |
|--------|--------|--------|
| 单元格 | 单元格 | 单元格 |
| 单元格 | 单元格 | 单元格 |

表格会应用项目中的表格样式类（如 table table-bordered table-striped）。

五、目录（TOC）¶

正文中的 ##、### 等标题会自动参与目录生成；若模板中渲染了 TOC 区块，将显示标题锚点与层级。TOC 扩展配置为 baselevel: 2，即从二级标题起算。

六、Mermaid 流程图与图表¶

在产品详情、新闻详情、帖子详情的 Markdown 中，可使用 Mermaid 代码块绘制流程图、时序图等，前台会在浏览器中自动渲染。

6.1 写法¶

使用围栏代码块并指定语言为 mermaid：

```mermaid
flowchart TD
    A[开始] --> B{判断}
    B -->|是| C[结果一]
    B -->|否| D[结果二]


### 6.2 常用图类型示例

**流程图（flowchart）**

```mermaid
flowchart LR
    A[输入] --> B[处理]
    B --> C[输出]

时序图（sequenceDiagram）

sequenceDiagram
    participant 用户
    participant 系统
    用户->>系统: 请求
    系统->>用户: 响应

类图（classDiagram）

classDiagram
    class 动物 {
        +名称
        +吃()
    }
    动物 <|-- 狗

状态图（stateDiagram）

stateDiagram-v2
    [*] --> 待处理
    待处理 --> 进行中: 开始
    进行中 --> 已完成: 完成

更多语法请参考 Mermaid 官方文档。

6.3 说明¶

Mermaid 块仅在产品详情、新闻详情、帖子详情的前台页面中渲染；关于我们等其它使用 Markdown 的页面如未引入 Mermaid 脚本则不会渲染。
宽图会在容器内横向滚动（.markdown-body .mermaid 已设置 overflow-x: auto）。

七、社区帖子与回复：表情语法¶

在社区帖子与回复中，除标准 Markdown 外，还支持表情简写：

[em]表情ID[/em]

在编辑区使用表情选择器插入后，会显示为对应表情图片。表情 ID 与 static/expression/ 下资源对应。

八、安全与限制¶

前台会对 Markdown 转换后的 HTML 做白名单过滤（如使用 bleach），仅允许安全标签与属性，防止 XSS。
允许的标签包括：p、br、strong、em、h1～h6、ul、ol、li、blockquote、pre、code、a、img、table、div、span 等；不允许任意 script、iframe 或未允许的属性。
代码块与 Mermaid 块由服务端/前端按规范处理，无需在正文中手写未转义的 HTML/脚本。

编写内容时遵循上述语法即可在对应场景下正确显示；若遇未支持的语法或显示异常，可对照本说明与各页面的「使用 Markdown」开关及控制台报错排查。

置顶推荐

版块目录

热门标签