@kernelift/markdown 1.1.0 → 1.1.2

package/README.md

@@ -1,13 +1,364 @@
-# @kernelift/markdown
-
-`markdown-it` 和 `monaco-editor` 的结合
-
-## 使用
-
-建议添加 `markdown` 渲染样式，也可以使用 `tailwind prose` 样式
-
-```vue
-<template>
-  <MarkdownRender class="prose"></MarkdownRender>
-</template>
-```
+# @kernelift/markdown
+
+基于 `markdown-it` 和 `highlight.js` 的 Markdown 渲染组件，提供强大的 Markdown 渲染和代码高亮功能。
+
+## 功能特性
+
+- 基于 `markdown-it` 的完整 Markdown 语法支持
+- 集成 `highlight.js` 代码高亮，支持多种编程语言
+- 代码块带行号显示
+- 代码块支持一键复制
+- 代码块支持折叠/展开（超过指定行数自动折叠）
+- 代码块行号与内容滚动同步
+- 表格样式美化，支持斑马纹和悬停效果
+- 支持自定义 Markdown 渲染配置
+- 支持自定义插件扩展
+- 支持暗黑模式样式
+- 响应式设计
+- 提供 `MdRender`（带完整样式）和 `MdRenderSimple`（简化版）两个组件
+
+## 安装
+
+```bash
+pnpm add @kernelift/markdown
+```
+
+## 基础用法
+
+### 简单示例
+
+```vue
+<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 样式
+
+```vue
+<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>
+```
+
+### 自定义代码块配置
+
+```vue
+<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 配置
+
+```vue
+<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>
+```
+
+### 使用自定义插件
+
+```vue
+<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 方法
+
+```vue
+<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>
+```
+
+### 暗黑模式
+
+```vue
+<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>
+```
+
+### 使用简化版组件
+
+```vue
+<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` 插件使用：
+
+```vue
+<template>
+  <MdRender v-model="content" class="prose prose-sm max-w-none" />
+</template>
+```
+
+### 自定义样式
+
+可以通过 CSS 变量自定义样式：
+
+```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
+
+## 类型定义
+
+```typescript
+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

package/dist/index.d.ts

@@ -12,6 +12,9 @@ declare type __VLS_Props = {
     options?: MarkdownItOptions;
     onCopy?: (code: string) => void;
     copyText?: string;
+    expandText?: string;
+    collapseText?: string;
+    codeMaxHeight?: number;
 };
 
 declare type __VLS_Props_2 = {
@@ -42,6 +45,9 @@ execMethods: (fn: (renderInstance: default_2) => void) => void;
 plugins: Array<any>;
 options: MarkdownItOptions;
 copyText: string;
+expandText: string;
+collapseText: string;
+codeMaxHeight: number;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {
 containerRef: HTMLDivElement;
 }, HTMLElement>;