> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 语法参考

> SoMarkDown 全部组件的语法说明与示例

## 1. 标题

支持 CommonMark 标准的六级标题，以 `#` 数量区分层级。

```markdown theme={null}
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
```

***

## 2. 正文与文字样式

### 基本样式

| 效果      | 语法                  |
| ------- | ------------------- |
| **加粗**  | `**文字**` 或 `__文字__` |
| *倾斜*    | `*文字*` 或 `_文字_`     |
| ==高亮==  | `==文字==`            |
| 上标      | `文字^上标^`            |
| 下标      | `文字~下标~`            |
| ~~删除线~~ | `~~文字~~`            |

```markdown theme={null}
**加粗的文字**
*倾斜的文字*
==高亮的文字==
这是^上标^
这是~下标~
~~删除线样式~~
```

### 下划线

下划线使用 `++` 包裹，每 2 个 `+` 表示一条下划线，多层嵌套可增加 `+` 的数量：

```markdown theme={null}
++下划线样式++
++++双层下划线++++
```

### 引用

```markdown theme={null}
> 引用文字
>
> 可以多段
```

***

## 3. 特殊符号

### Emoji

遵循 [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji) 规范，使用 `:emoji_name:` 语法。

### 版权符号

| 字符 | 写法              |
| -- | --------------- |
| ©  | `(c)` 或 `(C)`   |
| ®  | `(r)` 或 `(R)`   |
| ™  | `(tm)` 或 `(TM)` |

***

## 4. 列表

### 有序列表

```markdown theme={null}
1. 第一项
2. 第二项
3. 第三项
```

### 无序列表

以 `*`、`+` 或 `-` 起始均可：

```markdown theme={null}
- 第一项
- 第二项
  - 嵌套子项
```

***

## 5. 目录

使用 `[[TOC]]` 在文档中插入自动生成的目录，基于文档标题结构生成。

```markdown theme={null}
[[TOC]]
```

实现参考：[markdown-it-table-of-contents](https://github.com/cmaas/markdown-it-table-of-contents)

***

## 6. 代码

代码高亮由 [highlight.js](https://github.com/highlightjs/highlight.js) 提供，语言标识遵循 highlight.js 规范。

### 行内代码

```markdown theme={null}
使用 `print()` 函数输出文本。
```

### 代码块

````markdown theme={null}
```python
def hello():
    print("Hello, SoMarkDown!")
```
````

支持语言包括 `python`、`javascript`、`typescript`、`java`、`c`、`cpp`、`bash`、`sql`、`json` 等；如果你需要先了解整体定位和安装方式，回到 [SoMarkDown 概览](/open-source-tools/somarkdown/index)。完整列表见 [highlight.js 支持的语言](https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md)。

***

## 7. 数学公式

数学公式由 [KaTeX](https://katex.org) 渲染，语法与 LaTeX 一致。

### 行内公式

```markdown theme={null}
质能方程 $E = mc^2$ 是物理学的基础。
```

### 行间公式

```markdown theme={null}
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
```

***

## 8. 图片

```markdown theme={null}
![图片理解内容](图片地址)
```

SoMarkDown 将原 Markdown 语法中的"图片占位描述"借用为**图片语义理解**内容的放置处。在 SoMarkDown 渲染器中，方括号内的文字会作为 AI 对图片的语义描述特殊展示，同时又完全兼容原生 Markdown 的 alt 文字用法。

```markdown theme={null}
![该图表展示了 2020-2024 年的用户增长趋势，呈指数级上升。](https://example.com/chart.png)
```

可通过配置 `imgDescEnabled` 控制是否显示图片描述：

```javascript theme={null}
new SoMarkDown({ imgDescEnabled: true })
```

***

## 9. 表格

SoMarkDown 采用 HTML `<table>` 标签表示表格，比 Markdown 原生表格语法更通用，且支持合并单元格（`rowspan` / `colspan`）。

```html theme={null}
<table>
  <thead>
    <tr>
      <th>列 A</th>
      <th>列 B</th>
      <th>列 C</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="2">合并单元格</td>
      <td>B1</td>
      <td>C1</td>
    </tr>
    <tr>
      <td>B2</td>
      <td>C2</td>
    </tr>
  </tbody>
</table>
```

***

## 10. 图表例（Caption）

Caption 可用于为图片或表格添加标题说明，以 `: ` 起始（英文冒号 + 空格）。

```markdown theme={null}
: 图 1 — 用户增长趋势图

![图表](chart.png)
```

**规则：**

* 必须以 `: `（英文冒号 + 一个空格）起始
* 必须紧贴目标组件（Table 或 Figure）的上方或下方，中间允许有空行，但不能有其他组件
* 若上下方同时存在 Caption，优先选取上方

实现参考：[Pandoc Caption 规范](https://pandoc.org/MANUAL.html#extension-table_captions)

***

## 11. 化学方程式

化学方程式使用 `\ce{}` 语法，由 [mhchem](https://mhchem.github.io/MathJax-mhchem) 渲染，需放置在公式环境内。

### 行内

```markdown theme={null}
反应 $\ce{H2 + O2 -> H2O}$ 是放热反应。
```

### 行间

```markdown theme={null}
$$
\ce{2H2 + O2 ->[\text{点燃}] 2H2O}
$$
```

***

## 12. 化学结构式（SMILES）

化学结构式使用 `\smiles{}` 语法，由 [SmilesDrawer](https://github.com/reymond-group/smilesDrawer) 渲染，同样需要在公式环境内使用。

<Note>
  SoMarkDown 将 SMILES 视为公式环境中的一种特殊符号，原因是：(1) 结构式会出现在化学方程式中；(2) 和数学公式一样存在行内与行间两种排版需求；(3) 与化学方程式的集成方式保持一致。
</Note>

### 行内结构式

```markdown theme={null}
乙醇的结构式为 $\smiles{CCO}$。
```

### 行间结构式

```markdown theme={null}
$$
\smiles{c1ccccc1}
$$
```

### 化学结构方程式（mhchem + SMILES 混合）

SoMarkDown 创新支持在 `\ce{}` 内嵌入 `\smiles{}`，将化学结构式与方程式语法合并，满足在方程式中表达结构式的需求：

```markdown theme={null}
$$
\ce{\smiles{CCO} + \smiles{O} -> \smiles{CC(O)O}}
$$
```

SMILES 渲染可通过配置调整：

```javascript theme={null}
new SoMarkDown({
  smiles: {
    disableColors: false,
    width: 300,
    height: 200
  }
})
```

***

## 13. 流程图（即将支持）

Mermaid 流程图支持正在开发中，届时将使用以下语法：

````markdown theme={null}
```mermaid
graph TD
  A[开始] --> B{判断}
  B -->|是| C[执行]
  B -->|否| D[结束]
```
````