@bamaolink/markdown-html-viewer

一个功能丰富的 Markdown 渲染器，支持代码高亮、数学公式、Mermaid 图表、自定义容器等，同时提供 JavaScript API 和 Web Component 两种使用方式。

特性

• 代码高亮 — 基于 Prism.js，支持行号、语言标签、一键复制
• 数学公式 — 基于 KaTeX，支持行内 $...$ 和块级 $$...$$
• Mermaid 图表 — 流程图、时序图、甘特图等
• 自定义容器 — tip / warning / danger / info / success / details
• 任务列表 — 带自定义复选框样式
• 分页符 — :::pagebreak 语法
• 上下标 — ^上标^ 和 ~下标~
• Emoji — :emoji_name: 语法
• 锚点导航 — 自动生成标题锚点，支持 TOC 联动高亮
• 明暗主题 — 跟随系统 prefers-color-scheme 自动切换
• Web Component — <markdown-html-viewer> 自定义元素，import 即用

安装

pnpm add @bamaolink/markdown-html-viewer

使用

JavaScript API

import { MarkdownHtmlRender } from "@bamaolink/markdown-html-viewer";

const viewer = document.getElementById("viewer")!;
const toc = document.getElementById("toc")!;

const md = new MarkdownHtmlRender({ viewer, toc });
md.init();
md.value = "# Hello World";

Web Component

<script type="module">
  import "@bamaolink/markdown-html-viewer/web-component";
</script>

<markdown-html-viewer value="# Hello World"></markdown-html-viewer>

通过 JS 动态设置内容：

const el = document.querySelector("markdown-html-viewer");
el.value = "# 新内容\n\n支持 **Markdown** 语法";

显示 TOC 目录：

<!-- attribute 方式 -->
<markdown-html-viewer toc value="# Hello"></markdown-html-viewer>

// property 方式
el.options = { showToc: true };

// 访问 TOC 容器元素（可自行定位/样式化）
el.tocElement; // HTMLDivElement

传入 markdown-it 配置：

el.options = {
  showToc: true,
  markdownItOptions: { html: true, breaks: true },
};

单独引入样式

如果使用 JavaScript API 方式，样式会随模块自动加载。也可以单独引入：

import "@bamaolink/markdown-html-viewer/style.css";

API

MarkdownHtmlRender

| 属性/方法 | 类型 | 说明 | |---|---|---| | constructor(opts) | MarkdownHtmlRenderOptions | 创建实例 | | init() | () => void | 初始化 markdown-it 及所有插件 | | value | string | 设置/获取 Markdown 内容，赋值后自动渲染 |

MarkdownHtmlRenderOptions

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | viewer | HTMLElement | 是 | 渲染输出的容器元素 | | toc | HTMLElement | 否 | TOC 目录容器，传入后自动生成目录并高亮当前标题 | | markdownItOptions | markdown-it.Options | 否 | 覆盖默认的 markdown-it 配置 |

<markdown-html-viewer> Web Component

| 属性 | 类型 | 方式 | 说明 | |---|---|---|---| | value | string | attribute / property | Markdown 内容 | | toc | boolean | attribute | 是否显示 TOC 目录（布尔属性，添加即启用） | | options | WebComponentOptions | property | 渲染配置 | | tocElement | HTMLDivElement \| null | property (只读) | TOC 容器元素 |

WebComponentOptions

| 字段 | 类型 | 说明 | |---|---|---| | showToc | boolean | 是否显示 TOC（优先级高于 toc attribute） | | toc | HTMLElement | 自定义外部 TOC 容器元素 | | markdownItOptions | markdown-it.Options | 覆盖默认的 markdown-it 配置 |

自定义容器语法

:::tip 提示标题
这是一段提示内容。
:::

:::warning
默认标题为"警告"。
:::

:::danger 危险操作
请谨慎操作！
:::

:::info
信息说明。
:::

:::success
操作成功。
:::

:::details 点击展开
折叠内容。
:::

项目结构

src/
  lib/                        # 库代码（发布到 npm）
    index.ts                  # 主入口，导出 MarkdownHtmlRender
    types.ts                  # 类型定义
    renderer.ts               # 核心渲染类
    toc.ts                    # TOC 导航 IntersectionObserver
    web-component.ts          # <markdown-html-viewer> 自定义元素
    plugins/                  # markdown-it 插件
      container/              # 自定义容器 :::tip / :::warning 等
      math/                   # KaTeX 数学公式
      mermaid/                # Mermaid 图表
      pagebreak/              # 分页符
      prism/                  # 代码高亮（行号、复制按钮）
      sub/                    # 下标
      sup/                    # 上标
      taskLists/              # 任务列表
    styles/                   # 模块化 CSS
      index.css               # 汇总入口
      theme.css               # 明暗主题变量
      base.css                # 基础排版
      elements.css            # HTML 元素样式
      toc.css                 # TOC 目录导航
      code-block.css          # 代码块
      task-list.css           # 任务列表
      container.css           # 自定义容器
      pagebreak.css           # 分页符
      mermaid.css             # Mermaid 图表
  demo/                       # 开发调试用 Demo（不随包发布）
    main.ts
    style.css

开发

# 启动开发服务器
pnpm dev

# 构建库
pnpm build:lib

License

MIT