通用 Markdown 语法

📋 更新历史

日期	版本	更新内容
2025-11-06	v1.1.0	新增 ICON 图标声明语法
2025-08-15	v1.0.0	初始版本

PSUIP (Particle Service User Interface Protocol) 是基于 Markdown 的扩展协议，支持标准 Markdown 语法并提供额外的语义组件支持。

标准 Markdown 语法映射

PSUIP 支持标准的 Markdown 语法，下表展示了标准 Markdown 格式在 PSUIP 中对应的 UI 语义组件：

Markdown 语法	PSUIP 语义组件	示例
`# 一级标题`	h1 标题组件	`# 文档标题`
`## 二级标题`	h2 标题组件	`## 章节标题`
`### 三级标题`	h3 标题组件	`### 小节标题`
`#### 四级标题`	h4 标题组件	`#### 子标题`
`##### 五级标题`	h5 标题组件	`##### 详细标题`
普通文本	正文文本组件	这是一段普通文本
`> 引用文本`	引用文本组件	`> 这是引用内容`
`[超链接](https://example.com)`	primary 按钮组件	`[访问网站](https://example.com)`
`![图片](url)`	图片组件	`![示例图片](https://example.com/image.jpg)`
`表格语法（\| --- \| --- \|）`	表格组件	标准表格格式
代码语法（\```javascript \```）	代码组件	代码块显示
`LaTeX 数学公式（$$ formula $$）`	数学公式组件	`$$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$`
有序列表/无序列表	列表组件	`- 列表项 1`

语法示例

标题层次结构


# 主标题
## 二级标题  
### 三级标题
#### 四级标题
##### 五级标题

文本格式


这是**粗体文本**，这是*斜体文本*，这是`行内代码`。
 
> 这是一个引用块，用于强调重要信息或引用他人的话。

列表


无序列表：
- 项目 1
- 项目 2
- 项目 3
 
有序列表：
1. 第一项
2. 第二项
3. 第三项

代码块


行内代码：`console.log('Hello World')`
 
代码块：
\```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
\```

数学公式


行内公式：$E = mc^2$
 
块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

超链接语法增强

在 PSUIP 中，超链接语法对应按钮组件，因此对超链接语法进行了增强，使其可以表示不同语义的按钮类型。

按钮类型语法

PSUIP 增强语法	PSUIP 语义组件	说明
`[primary][主要按钮](https://example.com)`	primary 按钮组件	主要操作按钮，通常用于关键行为
`[secondary][次要按钮](https://example.com)`	secondary 按钮组件	次要操作按钮，辅助功能
`[success][成功按钮](https://example.com)`	success 按钮组件	表示成功或完成状态
`[warning][警告按钮](https://example.com)`	warning 按钮组件	警告或需要注意的操作
`[error][错误按钮](https://example.com)`	error 按钮组件	危险或删除类操作
`[ghost][幽灵按钮](https://example.com)`	ghost 按钮组件	透明背景的轻量级按钮
`[link][链接按钮](https://example.com)`	link 按钮组件	文本链接样式的按钮

按钮语法规范

增强的超链接语法遵循以下规范：

语法结构：[类型][显示文本](链接地址)
类型定义：必须是预定义的按钮类型之一
显示文本：按钮上显示的文字内容
链接地址：点击按钮后跳转的 URL

使用示例


<!-- 标准超链接（默认为 primary 按钮） -->
[访问官网](https://example.com)
 
<!-- 不同类型的按钮 -->
[primary][立即开始](https://example.com/start)
[secondary][了解更多](https://example.com/learn)
[success][注册成功](https://example.com/success)
[warning][谨慎操作](https://example.com/warning)
[error][删除账户](https://example.com/delete)
[ghost][取消](https://example.com/cancel)
[link][查看详情](https://example.com/details)

注意事项

类型名称：必须使用小写字母，不支持自定义类型
兼容性：标准的 [文本](链接) 语法仍然支持，默认渲染为 primary 按钮
嵌套：不支持按钮内嵌套其他 Markdown 元素
样式：按钮的具体视觉样式由当前主题的设计令牌（Design Token）决定

图标（ICON）语法 v1.1.0 新增

PSUIP 支持通过简洁的语法在文档中插入图标，内置字节跳动的 IconPark 图标库。

语法规范


[icon:类别名/图标名]

图标库

PSUIP 内置使用 IconPark 图标库（字节跳动开源），提供丰富的图标资源。

图标库特点：

2000+ 高质量图标
多种风格：线性、填充、双色、四色
完整的分类体系
支持自定义颜色和尺寸

图标分类

IconPark 图标按功能分类，常用分类包括：

类别	说明	示例
`Base`	基础图标	home, user, setting
`Brand`	品牌图标	github, wechat, alipay
`Abstract`	抽象图形	check, close, arrow
`Character`	字符/表情	smile, heart, star
`Edit`	编辑相关	edit, delete, copy
`Operate`	操作相关	search, filter, sort
`Charts`	图表图标	chart, trend, data
`Communicate`	通讯相关	mail, phone, message

使用示例

基础图标：


[icon:Base/home] 首页
[icon:Base/user] 个人中心
[icon:Base/setting] 系统设置

编辑图标：


[icon:Edit/edit] 编辑
[icon:Edit/delete] 删除
[icon:Edit/save] 保存

品牌图标：


[icon:Brand/github] GitHub
[icon:Brand/wechat] 微信
[icon:Brand/alipay] 支付宝

图表图标：


[icon:Charts/chart-line] 趋势图
[icon:Charts/chart-pie] 饼状图
[icon:Charts/data-display] 数据展示

图标在组件中使用

图标可以与其他 Markdown 元素组合使用：

在标题中使用：


## [icon:Base/home] 欢迎页面
 
### [icon:Edit/setting] 系统配置
 
#### [icon:Charts/data] 数据分析

在列表中使用：


- [icon:Abstract/check] 任务已完成
- [icon:Abstract/processing] 进行中
- [icon:Abstract/pause] 已暂停

在按钮中使用：


[icon:Base/save] [保存设置](https://example.com/save)
[secondary][icon:Edit/edit] [编辑内容](https://example.com/edit)

在卡片中使用：


<card:elegantStandard>
## [icon:Base/announcement] 重要公告
 
[icon:Abstract/info] 系统将于今晚进行维护升级
</card:elegantStandard>

图标样式

图标的默认样式由当前主题的设计令牌定义，包括：

尺寸：small (16px), medium (24px), large (32px)
颜色：继承当前文本颜色或主题色
对齐：与文本基线对齐

查找图标

推荐方式：

访问 IconPark 官网
浏览或搜索所需图标
记录图标的类别和名称
使用 [icon:类别/名称] 语法

常用图标快速参考：


<!-- 操作类 -->
[icon:Edit/edit] [icon:Edit/delete] [icon:Edit/save] [icon:Edit/copy]
 
<!-- 状态类 -->
[icon:Abstract/check] [icon:Abstract/close] [icon:Abstract/info] [icon:Abstract/warning]
 
<!-- 导航类 -->
[icon:Base/home] [icon:Base/back] [icon:Base/right] [icon:Base/menu]
 
<!-- 文件类 -->
[icon:Files/file] [icon:Files/folder] [icon:Files/upload] [icon:Files/download]

注意事项

图标名称：必须使用正确的类别名和图标名，区分大小写
图标库：当前仅支持 IconPark 图标库
性能：图标以 SVG 格式加载，性能优秀
自定义：暂不支持自定义图标库，但支持通过设计令牌调整颜色和尺寸

错误处理

当图标名称不存在时：

显示占位符图标
在控制台输出警告信息
不影响页面其他内容的渲染


<!-- 错误示例：不存在的图标 -->
[icon:Invalid/notexist]  <!-- 将显示占位符 -->
 
<!-- 正确示例 -->
[icon:Base/home]  <!-- 正常显示 -->

兼容性说明

PSUIP 完全兼容标准 Markdown 语法，所有标准 Markdown 文档都可以在 PSUIP 中正常渲染。增强语法（如按钮类型、图标）是可选的，不使用增强语法不会影响文档的正常显示。