@kernelift/markdown

基于 markdown-it 和 highlight.js 的 Markdown 渲染组件，提供强大的 Markdown 渲染和代码高亮功能。

功能特性

• 基于 markdown-it 的完整 Markdown 语法支持
• 集成 highlight.js 代码高亮，支持多种编程语言
• 代码块带行号显示
• 代码块支持一键复制
• 代码块支持折叠/展开（超过指定行数自动折叠）
• 代码块行号与内容滚动同步
• 表格样式美化，支持斑马纹和悬停效果
• 支持自定义 Markdown 渲染配置
• 支持自定义插件扩展
• 支持暗黑模式样式
• 响应式设计
• 提供 MdRender（带完整样式）和 MdRenderSimple（简化版）两个组件

安装

pnpm add @kernelift/markdown

基础用法

简单示例

<script setup lang="ts">
import { ref } from 'vue';
import { MdRender } from '@kernelift/markdown';

const content = ref(`
# Hello World

这是一个 Markdown 渲染组件示例。

## 代码示例

\`\`\`javascript
function hello() {
  console.log('Hello, World!');
}
\`\`\`

## 表格示例

| 姓名 | 年龄 | 职业 |
|------|------|------|
| 张三 | 25 | 工程师 |
| 李四 | 30 | 设计师 |
`);
</script>

<template>
  <MdRender v-model="content" />
</template>

使用 Tailwind Prose 样式

<script setup lang="ts">
import { ref } from 'vue';
import { MdRender } from '@kernelift/markdown';

const content = ref('# Hello World');
</script>

<template>
  <MdRender v-model="content" class="prose" />
</template>

自定义代码块配置

<script setup lang="ts">
import { ref } from 'vue';
import { MdRender } from '@kernelift/markdown';

const content = ref(`
\`\`\`javascript
// 这是一个很长的代码块
function longFunction() {
  console.log('Line 1');
  console.log('Line 2');
  console.log('Line 3');
  // ... 更多代码
  console.log('Line 25');
}
\`\`\`
`);

const handleCopy = (code: string) => {
  console.log('复制代码:', code);
  navigator.clipboard.writeText(code);
};
</script>

<template>
  <MdRender 
    v-model="content" 
    :code-max-height="15"
    copy-text="复制"
    expand-text="查看更多"
    collapse-text="收起"
    :on-copy="handleCopy"
  />
</template>

自定义 Markdown 配置

<script setup lang="ts">
import { ref } from 'vue';
import { MdRender } from '@kernelift/markdown';
import type { MarkdownItOptions } from '@kernelift/markdown';

const content = ref('# Hello World');

const options: MarkdownItOptions = {
  html: false,          // 禁用 HTML 标签
  linkify: true,        // 自动识别链接
  breaks: true,         // 启用换行符
  typographer: true,    // 启用排版优化
  table: true           // 启用表格
};
</script>

<template>
  <MdRender 
    v-model="content" 
    :options="options" 
  />
</template>

使用自定义插件

<script setup lang="ts">
import { ref } from 'vue';
import { MdRender } from '@kernelift/markdown';
import markdownItEmoji from 'markdown-it-emoji';

const content = ref('Hello :smile: World!');

const plugins = [markdownItEmoji];
</script>

<template>
  <MdRender 
    v-model="content" 
    :plugins="plugins" 
  />
</template>

使用 Expose 方法

<script setup lang="ts">
import { ref } from 'vue';
import { MdRender } from '@kernelift/markdown';

const content = ref('# Hello World');
const renderRef = ref();

const getRenderedHtml = () => {
  renderRef.value?.execMethods((instance) => {
    const html = instance.render(content.value);
    console.log('渲染后的 HTML:', html);
  });
};

const parseInline = () => {
  renderRef.value?.execMethods((instance) => {
    const result = instance.parseInline('**粗体** *斜体*', {});
    console.log('解析结果:', result);
  });
};
</script>

<template>
  <div>
    <div style="margin-bottom: 10px;">
      <button @click="getRenderedHtml">获取渲染 HTML</button>
      <button @click="parseInline">解析内联文本</button>
    </div>
    <MdRender 
      ref="renderRef"
      v-model="content" 
    />
  </div>
</template>

暗黑模式

<script setup lang="ts">
import { ref } from 'vue';
import { MdRender } from '@kernelift/markdown';

const content = ref('# Hello World');
const isDark = ref(true);
</script>

<template>
  <div :class="{ dark: isDark }">
    <MdRender 
      v-model="content" 
      :class="{ dark: isDark }"
    />
  </div>
</template>

使用简化版组件

<script setup lang="ts">
import { ref } from 'vue';
import { MdRenderSimple } from '@kernelift/markdown';

const content = ref('# Hello World');
</script>

<template>
  <MdRenderSimple v-model="content" />
</template>

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | modelValue | Markdown 内容（v-model） | string | - | | plugins | 自定义插件数组 | Array<any> | [] | | options | MarkdownIt 配置选项 | MarkdownItOptions | 见下方默认配置 | | onCopy | 复制代码回调 | (code: string) => void | - | | copyText | 复制按钮文本 | string | '复制代码' | | expandText | 展开按钮文本 | string | '展开' | | collapseText | 收起按钮文本 | string | '收起' | | codeMaxHeight | 代码块最大高度（行数），超过则折叠 | number | 20 |

MarkdownItOptions 默认配置

| 参数 | 默认值 | 说明 | |------|--------|------| | html | true | 允许 HTML 标签 | | linkify | true | 自动识别链接 | | breaks | false | 启用换行符转换 | | typographer | true | 启用排版优化 | | table | true | 启用表格支持 | | xhtmlOut | false | 关闭 XHTML 严格模式 |

Emits

| 事件名 | 说明 | 参数 | |--------|------|------| | update:modelValue | 内容变化时触发 | (value: string) |

Expose

| 方法名/属性 | 说明 | 类型 | |-------------|------|------| | renderInstance | MarkdownIt 实例 | ShallowRef<MarkdownIt \| undefined> | | execMethods | 执行 MarkdownIt 实例方法 | (fn: (renderInstance: MarkdownIt) => void) => void |

组件对比

| 特性 | MdRender | MdRenderSimple | |------|----------|----------------| | 完整样式 | ✅ | ❌ | | 暗黑模式 | ✅ | ❌ | | 表格美化 | ✅ | ✅ | | 代码高亮 | ✅ | ✅ | | 代码块折叠 | ✅ | ✅ | | 代码块复制 | ✅ | ✅ | | 行号显示 | ✅ | ✅ | | 滚动同步 | ✅ | ✅ | | 体积 | 较大 | 较小 |

样式说明

内置样式

MdRender 组件内置了完整的 Markdown 渲染样式，包括：

• 标题样式（h1-h6）
• 段落样式
• 列表样式
• 引用样式
• 代码块样式
• 表格样式
• 链接样式
• 图片样式
• 分隔线样式

Tailwind Prose

如果使用 Tailwind CSS，可以配合 @tailwindcss/typography 插件使用：

<template>
  <MdRender v-model="content" class="prose prose-sm max-w-none" />
</template>

自定义样式

可以通过 CSS 变量自定义样式：

.kernelift-md-render {
  --markdown-text-color: #2c3e50;
}

代码高亮

组件使用 highlight.js 进行代码高亮，支持以下语言：

• JavaScript / TypeScript
• Python
• Java
• C / C++
• Go
• Rust
• PHP
• Ruby
• HTML / CSS
• Vue
• React (JSX)
• 等更多语言...

注意事项

1. 代码块默认超过 20 行会自动折叠，可通过 codeMaxHeight 调整
2. 使用 plugins 时，插件必须符合 markdown-it 插件规范
3. onCopy 回调优先于默认复制行为
4. 暗黑模式需要父容器或组件本身添加 dark 类名
5. MdRenderSimple 不包含内置样式，需要自行引入样式或使用 Tailwind Prose

类型定义

export type MarkdownItOptions = import('markdown-it').Options;

依赖

• markdown-it: ^14.1.0
• highlight.js: ^11.11.1
• lodash-es: ^4.17.21
• vue: ^3.5.22

许可证

GPL-3.0-only