@dykj/md2html

高质量 Markdown 转 HTML 转换器，支持代码高亮、数学公式和自定义主题

✨ 特性

• 📝 完整的 Markdown 支持 - 基于 markdown-it，支持 GFM 语法
• 🎨 代码高亮 - 使用 highlight.js 提供语法高亮
• 🧮 数学公式 - 支持 LaTeX 数学公式渲染（KaTeX）
• ✅ 任务列表 - GitHub 风格的任务列表
• 📊 图表支持 - Mermaid 和 PlantUML 图表
• 📑 自动目录 - 自动生成文档目录，固定在右侧
• 🔗 智能链接 - 自动转换 .md 链接为 .html
• 🖼️ 灵活的图片处理 - 支持相对路径、base64 嵌入、文件复制
• 🎭 多主题支持 - 内置 GitHub、Dark 等主题
• 📌 脚注支持 - Markdown 脚注语法
• 🖍️ 文本标记 - 支持 ==高亮文本==

📦 安装

全局安装

npm install -g @dykj01/html4md

🔄 自动版本检查

全局安装后,每次运行 html4md 命令时会自动检查版本:

• ✅ 版本一致: 静默通过
• ⚠️ 版本不一致: 提示是否更新,一键卸载旧版并安装新版

Node.js 项目中使用

npm install @dykj01/html4md

🚀 使用方法

命令行使用

# 基础转换
md2html input.md

# 指定输出文件
md2html input.md -o output.html

# 使用暗色主题
md2html input.md --theme dark

# 图片转 base64 嵌入
md2html input.md --image-mode base64

# 仅输出 HTML 片段(不含完整文档结构)
md2html input.md --fragment

# 检查本地版本与npm版本是否一致
md2html check-version

Node.js API

const MarkdownConverter = require('@dykj/md2html');

// 创建转换器实例
const converter = new MarkdownConverter({
  theme: 'github',        // 主题：github | dark
  fragment: false,        // 是否仅输出片段
  title: '我的文档',      // HTML 文档标题
  imageMode: 'relative'   // 图片模式：relative | base64 | copy
});

// 转换 Markdown 字符串
const html = converter.convert('# Hello World\n\nThis is **markdown**.');

// 转换文件
const html2 = converter.convertFile('input.md');

// 转换并保存
converter.convertAndSave('input.md', 'output.html');

⚙️ 配置选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | theme | string | 'github' | 主题样式（github, dark） | | fragment | boolean | false | 是否仅输出 HTML 片段 | | title | string | 'Markdown Document' | HTML 文档标题 | | basePath | string | process.cwd() | Markdown 文件所在目录 | | imageMode | string | 'relative' | 图片处理模式 | | outputDir | string | null | 输出目录（imageMode=copy 时使用） |

图片处理模式

• relative - 保持相对路径不变（默认）
• base64 - 将图片转换为 base64 嵌入 HTML
• copy - 复制图片到输出目录

📝 支持的 Markdown 语法

基础语法

# 标题 1
## 标题 2
### 标题 3

**粗体** *斜体* ~~删除线~~ ==高亮==

- 无序列表
- 项目 2

1. 有序列表
2. 项目 2

[链接](https://example.com)
![图片](image.png)

任务列表

- [x] 已完成任务
- [ ] 未完成任务

代码块

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

数学公式

行内公式：$E = mc^2$

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

Mermaid 图表

```mermaid
graph TD
    A[开始] --> B[处理]
    B --> C[结束]
```

PlantUML 图表

```plantuml
@startuml
Alice -> Bob: Hello
Bob -> Alice: Hi!
@enduml
```

脚注

这是一段文字[^1]。

[^1]: 这是脚注内容

表格

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据1 | 数据2 | 数据3 |

📑 自动目录

转换器会自动在文档中插入目录（TOC）：

• 如果文档有 h1 标题，目录会插入在 h1 后面
• 如果没有 h1，目录会插入在文档开头
• 也可以手动指定位置：[[toc]]

目录会固定显示在页面右侧（大屏幕），小屏幕自动隐藏。

🔍 版本检查

检查本地版本是否与 npm 上发布的版本一致:

# 使用本地安装的包
md2html check-version

# 使用 npx
npx @dykj01/html4md check-version

输出示例:

📦 Package: @dykj01/html4md
📍 Local version: 1.0.3
🔍 Checking npm registry...

🌐 NPM latest version: 1.0.3

✅ Version matched! Local version is up to date with npm.

如果版本不一致,会提示:

⚠️  Version mismatch!
   Local:  1.0.4
   NPM:    1.0.3
   💡 Local version is newer (not published yet?)

🎨 主题

GitHub 主题（默认）

md2html input.md --theme github

暗色主题

md2html input.md --theme dark

📄 许可证

MIT

👤 作者

dykj