CaptureMD

将 Markdown 转换为适合社交媒体发布的精美图片

一个基于 TypeScript 的 Node.js 库,可以将 Markdown 内容转换为精美的图片,特别适合小红书、朋友圈等社交媒体平台分享。支持数学公式、Mermaid 图表、自定义样式等丰富功能。

本项目基于 Madopic 进行 Node.js 环境的实现。

✨ 核心特性

🎨 精美样式 - 8 种内置渐变背景预设,支持自定义配色
📱 完美适配 - 专为小红书 3:4、朋友圈比例优化
🔢 数学公式 - 支持 KaTeX 行内和块级公式渲染
📊 图表支持 - 内置 Mermaid,支持流程图、序列图等
💎 卡片语法 - 创建 info/success/warning/error 样式卡片
⚙️ 高度定制 - 字体大小、内边距、背景色完全可控
🖼️ 高清输出 - 支持 2 倍及以上缩放,确保清晰度
📦 TypeScript - 完整类型定义,智能提示
🚀 简单易用 - 一行代码完成转换
🔌 离线可用 - 所有资源本地化,无需联网

📦 安装

npm install capture-md

或使用其他包管理器:

# Yarn
yarn add capture-md

# pnpm
pnpm add capture-md

环境要求:

Node.js >= 16.0.0
自动安装 Puppeteer (用于图片渲染)

🚀 快速开始

最简示例

三步即可完成 Markdown 到图片的转换:

import { md2image } from 'capture-md';

// 1. 准备 Markdown 内容
const markdown = '# Hello World\n\n这是一个**简单**的示例。';

// 2. 转换为图片
await md2image(markdown, {
  outputPath: './output.png',  // 指定输出路径
});

// 3. 完成!图片已生成

方式 1: 转换 Markdown 字符串

适合动态生成内容的场景:

import { md2image } from 'capture-md';

const markdown = `
# 你好,世界!

这是一个 **Markdown** 转图片的示例。

## 支持的功能

- 支持列表
- 支持 *斜体* 和 **粗体**
- 支持 \`行内代码\`

\`\`\`javascript
// 支持代码块
console.log('Hello World');
\`\`\`
`;

// 转换为小红书格式(3:4 比例)
await md2image(markdown, {
  mode: 'xhs',
  outputPath: './output.png',
});

方式 2: 从文件转换

适合转换现有的 Markdown 文档:

import { md2image } from 'capture-md';

// 自动生成同名 .png 文件
await md2image('./README.md', {
  mode: 'xhs',
});
// 生成 README.png

// 或指定输出路径
await md2image('./docs/guide.md', {
  mode: 'xhs',
  outputPath: './images/guide.png',
});

方式 3: 批量转换目录

适合批量处理多个文件:

import { md2imageDir } from 'capture-md';

// 转换目录中所有 .md 文件
const results = await md2imageDir('./docs', {
  mode: 'xhs',
});

console.log(`✅ 成功转换 ${results.length} 个文件`);

// 递归转换所有子目录
await md2imageDir('./docs', { mode: 'xhs' }, true);

📖 完整 API 参考

核心函数

`md2image(input, options?)`

主要转换函数,自动识别输入类型(字符串内容或文件路径)。

参数:

参数	类型	说明
`input`	`string`	Markdown 字符串内容或文件路径
`options`	`Md2ImageOptions`	可选配置项(见下方)

返回值: Promise<ConvertResult>

interface ConvertResult {
  imagePath: string;  // 生成的图片路径
  width: number;      // 图片宽度
  height: number;     // 图片高度
}

示例:

// 转换字符串
const result = await md2image('# Hello World');
console.log(result.imagePath);  // 输出: output-xxx.png

// 转换文件
await md2image('./README.md', { outputPath: './readme.png' });

`md2imageDir(dirPath, options?, recursive?)`

批量转换目录中的所有 Markdown 文件。

参数:

参数	类型	默认值	说明
`dirPath`	`string`	-	目录路径
`options`	`Md2ImageOptions`	`{}`	可选配置项
`recursive`	`boolean`	`false`	是否递归处理子目录

返回值: Promise<ConvertResult[]>

示例:

// 转换单个目录
const results = await md2imageDir('./docs');

// 递归转换所有子目录
const allResults = await md2imageDir('./docs', {}, true);

// 使用自定义配置
await md2imageDir('./docs', {
  mode: 'xhs',
  backgroundPreset: 'sunset'
}, true);

高级用法: Md2ImageConverter 类

当需要复用配置或批量转换时,使用 Md2ImageConverter 类可以提升性能(复用浏览器实例)。

完整示例:

import { Md2ImageConverter } from 'capture-md';

// 1. 创建转换器实例(复用配置和浏览器)
const converter = new Md2ImageConverter({
  mode: 'xhs',
  backgroundPreset: 'sunset',
  fontSize: 20,
});

// 2. 转换多个 Markdown 字符串
await converter.convert('# 文章 1', './output1.png');
await converter.convert('# 文章 2', './output2.png');

// 3. 从文件转换
await converter.convertFromFile('./README.md');

// 4. 批量转换
const results = await converter.convertBatch([
  { markdown: '# Title 1', outputPath: './1.png' },
  { markdown: '# Title 2', outputPath: './2.png' },
]);

// 5. 运行时更新配置
converter.updateOptions({ backgroundPreset: 'blue' });

// 6. 完成后关闭浏览器
await converter.close();

方法列表:

方法	说明	返回值
`convert(markdown, outputPath?)`	转换 Markdown 字符串	`Promise<ConvertResult>`
`convertFromFile(filePath, outputPath?)`	从文件转换	`Promise<ConvertResult>`
`convertFromDirectory(dirPath, outputDir?, recursive?)`	批量转换目录	`Promise<ConvertResult[]>`
`convertBatch(items)`	批量转换字符串数组	`Promise<ConvertResult[]>`
`updateOptions(options)`	更新配置	`void`
`close()`	关闭浏览器实例	`Promise<void>`

⚙️ 配置选项详解

完整配置接口

interface Md2ImageOptions {
  // 🎯 导出模式
  mode?: ExportMode | 'free' | 'xhs' | 'pyq';  // 默认: 'xhs'

  // 📐 尺寸相关
  width?: number;      // 图片宽度(像素), 默认: 640
  padding?: number;    // 内边距(像素), 默认: 40
  scale?: number;      // 导出缩放倍数, 默认: 2

  // ✏️ 字体相关
  fontSize?: number;   // 基础字体大小(像素), 默认: 18

  // 🎨 背景相关(二选一)
  backgroundPreset?: 'purple' | 'pink' | 'blue' | 'green' |
                     'sunset' | 'pastel' | 'peach' | 'rose';

  customBackground?: {
    colorStart: string;   // 渐变起始色, 如: '#667eea'
    colorEnd: string;     // 渐变结束色, 如: '#764ba2'
    direction: string;    // 渐变方向, 如: '135deg'
  };

  // 📂 输出相关
  outputPath?: string;  // 输出文件路径

  // 🔧 扩展功能
  extensions?: {
    enableMath?: boolean;      // 启用数学公式, 默认: true
    enableDiagram?: boolean;   // 启用 Mermaid 图表, 默认: true
    enableCard?: boolean;      // 启用卡片语法, 默认: true
  };
}

导出模式 (mode)

控制图片的宽高比和自适应行为:

模式	说明	适用场景
`xhs`	小红书模式,固定 3:4 比例	小红书发布(默认)
`pyq`	朋友圈模式,固定 1290:2796	微信朋友圈分享
`free`	自由模式,高度自适应内容	通用场景

使用示例:

import { md2image, ExportMode } from 'capture-md';

// 方式 1: 使用枚举(推荐,有类型提示)
await md2image(markdown, { mode: ExportMode.XHS });

// 方式 2: 使用字符串
await md2image(markdown, { mode: 'xhs' });

背景预设 (backgroundPreset)

内置 8 种精美渐变背景:

预设	描述	渐变颜色
`purple`	紫色梦幻	#667eea → #764ba2
`pink`	粉红热情	#f093fb → #f5576c
`blue`	天空蓝	#4facfe → #00f2fe
`green`	清新绿	#43e97b → #38f9d7
`sunset`	暖阳橙	#fa709a → #fee140
`pastel`	温柔粉	#a8edea → #fed6e3
`peach`	柔和橙	#ffecd2 → #fcb69f
`rose`	浪漫粉	#ff9a9e → #fecfef

使用示例:

await md2image(markdown, {
  backgroundPreset: 'sunset',  // 使用暖阳橙预设
});

自定义背景 (customBackground)

如果内置预设不满足需求,可以自定义渐变背景:

await md2image(markdown, {
  customBackground: {
    colorStart: '#FF6B6B',  // 起始颜色
    colorEnd: '#4ECDC4',    // 结束颜色
    direction: '45deg',     // 渐变方向
  },
});

🎨 扩展功能详解

💡 提示: 所有扩展功能使用本地资源,完全离线可用!

1. 数学公式 (KaTeX)

默认启用,支持行内和块级公式。

Markdown 语法:

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

块级公式:
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

禁用方式:

await md2image(markdown, {
  extensions: { enableMath: false }
});

2. Mermaid 图表

默认启用,支持流程图、序列图、甘特图等。

Markdown 语法:

```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
```

禁用方式:

await md2image(markdown, {
  extensions: { enableDiagram: false }
});

3. 卡片语法

使用特殊语法创建彩色卡片块。

Markdown 语法:

:::card info
📘 这是一个信息卡片
:::

:::card success
✅ 这是一个成功卡片
:::

:::card warning
⚠️ 这是一个警告卡片
:::

:::card error
❌ 这是一个错误卡片
:::

禁用方式:

await md2image(markdown, {
  extensions: { enableCard: false }
});

📝 更多示例

完整配置示例

结合所有配置选项的完整示例:

import { md2image, ExportMode } from 'capture-md';

await md2image(markdown, {
  // 导出模式
  mode: ExportMode.XHS,

  // 尺寸和样式
  width: 720,
  padding: 50,
  fontSize: 20,
  scale: 3,  // 3 倍高清

  // 背景
  backgroundPreset: 'sunset',

  // 输出
  outputPath: './my-output.png',

  // 扩展功能
  extensions: {
    enableMath: true,
    enableDiagram: true,
    enableCard: true,
  },
});

JavaScript (CommonJS) 用法

const { md2image } = require('capture-md');

async function convertMarkdown() {
  await md2image('# Hello World', {
    mode: 'xhs',
    outputPath: './output.png',
  });
}

convertMarkdown();

错误处理

import { md2image } from 'capture-md';

try {
  const result = await md2image('./article.md', {
    mode: 'xhs',
    outputPath: './output.png',
  });

  console.log(`✅ 转换成功!`);
  console.log(`📁 文件路径: ${result.imagePath}`);
  console.log(`📐 尺寸: ${result.width}x${result.height}`);
} catch (error) {
  console.error('❌ 转换失败:', error.message);
}

🎯 使用场景

社交媒体

📱 小红书 - 使用 mode: 'xhs',完美适配 3:4 比例
💬 微信朋友圈 - 使用 mode: 'pyq',适配朋友圈分享
📸 Instagram/微博 - 使用 mode: 'free',自适应内容高度

内容创作

📚 知识卡片 - 制作精美的知识分享图片
💡 技术教程 - 将代码片段和说明转为图片
📊 数据报告 - 结合图表功能展示数据
📖 读书笔记 - 将文字笔记转为精美图片

教育场景

🎓 在线教学 - 制作课件和教学材料
🔢 数学题目 - 利用公式支持展示数学内容
📝 学习笔记 - 转换笔记为可分享的图片

❓ 常见问题

如何提高图片质量?

使用更高的 scale 值:

await md2image(markdown, {
  scale: 3,  // 3 倍高清,文件会更大
});

如何更改图片宽度?

await md2image(markdown, {
  width: 720,  // 默认 640
});

支持哪些 Markdown 语法?

✅ 标题 (H1-H6)
✅ 粗体、斜体、删除线
✅ 列表(有序、无序)
✅ 代码块和行内代码
✅ 引用块
✅ 链接和图片
✅ 表格
✅ 数学公式 (KaTeX)
✅ Mermaid 图表
✅ 自定义卡片语法

为什么首次运行很慢?

首次运行时 Puppeteer 需要下载 Chromium 浏览器,之后就会很快了。

如何在 Docker 中使用?

需要安装 Chromium 依赖:

RUN apt-get update && apt-get install -y \
    chromium \
    ca-certificates \
    fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

🔧 技术栈

TypeScript - 类型安全的开发体验
Puppeteer - 无头浏览器渲染引擎
Marked - 高性能 Markdown 解析器
KaTeX - 快速数学公式渲染
Mermaid - 强大的图表绘制库

设计灵感来自 Madopic 的精美样式。

📄 开源协议

MIT License - 详见 LICENSE 文件

本项目基于 Madopic 进行 Node.js 环境的实现,Madopic 同样采用 MIT 许可证。

🤝 参与贡献

欢迎提交 Issue 和 Pull Request!

如有问题或建议,请访问 GitHub Issues。

🙏 致谢

Madopic - 本项目的灵感来源
感谢 @xiaolinbaba 的精美设计

⭐️ 如果这个项目对你有帮助,欢迎给个 Star!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

CaptureMD

✨ 核心特性

📦 安装

🚀 快速开始

最简示例

方式 1: 转换 Markdown 字符串

方式 2: 从文件转换

方式 3: 批量转换目录

📖 完整 API 参考

核心函数

md2image(input, options?)

md2imageDir(dirPath, options?, recursive?)

高级用法: Md2ImageConverter 类

⚙️ 配置选项详解

完整配置接口

导出模式 (mode)

背景预设 (backgroundPreset)

自定义背景 (customBackground)

🎨 扩展功能详解

1. 数学公式 (KaTeX)

2. Mermaid 图表

3. 卡片语法

📝 更多示例

完整配置示例

JavaScript (CommonJS) 用法

错误处理

🎯 使用场景

社交媒体

内容创作

教育场景

❓ 常见问题

如何提高图片质量?

如何更改图片宽度?

支持哪些 Markdown 语法?

为什么首次运行很慢?

如何在 Docker 中使用?

🔧 技术栈

📄 开源协议

🤝 参与贡献

🙏 致谢

`md2image(input, options?)`

`md2imageDir(dirPath, options?, recursive?)`