Markdown 渲染器

把 Markdown 文本渲染成 HTML。零依赖自带解析器。

基础用法

标题

这是一段普通文本，支持 粗体、斜体 与 行内代码。

二级标题

• 列表项一
• 列表项二
• 列表项三

引用块：适合放注意事项或补充说明。

链接文本

<script setup>
const content = `# 标题

支持 **粗体**、*斜体* 与 \`行内代码\`。
`
</script>

<template>
  <SrMarkdown :content="content" />
</template>

为什么自带解析器

Markdown 渲染的常见方案是 marked 或 markdown-it。本库自己实现的原因：

1. 需要与组件库的视觉令牌统一。第三方解析器的产物是裸 HTML， 样式要另写一套；自带解析器可以直接输出带 .sr-md__* 类名的结构， 颜色、间距、圆角全部走 L2 / L3 令牌，切主题自动跟随。
2. 代码块要高亮。marked 输出的 <pre><code> 还需要再接一个高亮库， 而本库已有 SrCodeBlock，风格一致、不重复引入。
3. 可控的攻击面。第三方解析器的配置项繁多（html、linkify、 breaks…），配错一项就可能引入 XSS。自家实现只做需要的那部分。

自带解析器的能力边界

支持 CommonMark 的核心语法：标题、强调、链接、图片、列表、引用、 代码块、行内代码、分隔线、表格。

不支持：脚注、定义列表、数学公式、Mermaid 图表、HTML 内联。 需要这些时请换用专业方案。

代码块

代码块会自动套用 SrCodeBlock，因此行号与复制按钮都是现成的。

代码块

ts

1 2 3

import { ref } from 'vue'

const count = ref(0)

行内代码 const a = 1 也会被正确渲染。

<SrMarkdown :content="content" code-line-numbers />

代码块

ts

1 2 3

import { ref } from 'vue'

const count = ref(0)

行内代码 const a = 1 也会被正确渲染。

code-copyable="false"：关闭复制按钮

<SrMarkdown :content="content" :code-copyable="false" />

表格

名称	类型	默认值
size	`'sm' \\	'md'`
disabled	boolean	false

左对齐	居中	右对齐
A	B	C

<SrMarkdown :content="content" />

表格支持列对齐（:--- 左对齐、:---: 居中、---: 右对齐）。

表格里的竖线要转义

单元格内容里的 | 会与列分隔符冲突，需写成 \|。 这是 Markdown 表格的固有限制，不是解析器的问题。

关于 XSS

默认不渲染任何 HTML

解析器把所有 HTML 标签当普通文本转义输出，因此不存在 「用户输入 <script> 被执行」的风险。

这是有意的取舍：允许内联 HTML 能实现更多效果，但几乎所有 「Markdown 渲染导致 XSS」的案例都源于此。评论、备注这类 用户可编辑的内容，安全比灵活重要。

若确实需要渲染 HTML，请在渲染前用可信的白名单库自行清洗， 不要把原始内容直接喂给渲染器。

表情

emoji-packages 传入表情包数据后，: 包裹的短代码会被渲染成表情。

支持表情短代码 :smile: :heart:

<SrMarkdown :content="content" :emoji-packages="packages" />

尺寸

大号

正文内容。

<SrMarkdown :content="content" size="sm" />
<SrMarkdown :content="content" size="lg" />

Props

名称	类型	默认值	说明
content	string	''	Markdown 源文本
size	'sm' | 'md' | 'lg'	'md'	尺寸
codeLineNumbers	boolean	false	代码块是否显示行号
codeCopyable	boolean	true	代码块是否显示复制按钮
emojiPackages	SrEmojiPackage[]	—	表情包数据，用于渲染 :shortcode:

支持的语法

语法	写法
标题	# 一级 ~ ###### 六级
粗体 / 斜体	**粗** / *斜*
删除线	~~删除~~
行内代码	`code`
代码块	```lang
链接 / 图片	[文字](url) / 
列表	- 项 / 1. 项
任务列表	- [x] 已完成
引用	> 引用
分隔线	---
表格	| 列 | 列 |

无障碍

• 标题输出为真实的 <h1>–<h6>，读屏软件能按标题层级跳转 （很多第三方渲染器会把标题渲染成带样式的 <div>，那就丢失了导航能力）
• 图片的 alt 原样透传；没有 alt 的图片会加 role="presentation"， 避免读屏软件念出图片文件名
• 链接的外链会自动加 rel="noopener noreferrer"

相关

• 需要编辑（工具栏、分栏预览、表情面板）：SrMarkdownEditor —— 它的预览区直接复用本渲染器，因此编辑时所见与最终渲染一致
• 代码块高亮：SrCodeBlock