md2xhs 1.0.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 md2xhs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project is inspired by and based on Madopic (https://github.com/xiaolinbaba/Madopic)
+Madopic is licensed under the MIT License.

package/README.md

@@ -0,0 +1,622 @@
+# md2xhs
+
+> 将 Markdown 转换为适合社交媒体发布的精美图片
+
+一个基于 TypeScript 的 Node.js 库,可以将 Markdown 内容转换为精美的图片,特别适合小红书、朋友圈等社交媒体平台分享。支持数学公式、Mermaid 图表、自定义样式等丰富功能。
+
+**本项目基于 [Madopic](https://github.com/xiaolinbaba/Madopic) 进行 Node.js 环境的实现。**
+
+---
+
+## ✨ 核心特性
+
+- 🎨 **精美样式** - 8 种内置渐变背景预设,支持自定义配色
+- 📱 **完美适配** - 专为小红书 3:4、朋友圈比例优化
+- 🔢 **数学公式** - 支持 KaTeX 行内和块级公式渲染
+- 📊 **图表支持** - 内置 Mermaid,支持流程图、序列图等
+- 💎 **卡片语法** - 创建 info/success/warning/error 样式卡片
+- ⚙️ **高度定制** - 字体大小、内边距、背景色完全可控
+- 🖼️ **高清输出** - 支持 2 倍及以上缩放,确保清晰度
+- 📦 **TypeScript** - 完整类型定义,智能提示
+- 🚀 **简单易用** - 一行代码完成转换
+- 🔌 **离线可用** - 所有资源本地化,无需联网
+
+---
+
+## 📦 安装
+
+```bash
+npm install md2xhs
+```
+
+或使用其他包管理器:
+
+```bash
+# Yarn
+yarn add md2xhs
+
+# pnpm
+pnpm add md2xhs
+```
+
+**环境要求:**
+
+- Node.js >= 16.0.0
+- 自动安装 Puppeteer (用于图片渲染)
+
+---
+
+## 🚀 快速开始
+
+### 最简示例
+
+三步即可完成 Markdown 到图片的转换:
+
+```typescript
+import { md2image } from 'md2xhs';
+
+// 1. 准备 Markdown 内容
+const markdown = '# Hello World\n\n这是一个**简单**的示例。';
+
+// 2. 转换为图片
+await md2image(markdown, {
+  outputPath: './output.png',  // 指定输出路径
+});
+
+// 3. 完成!图片已生成
+```
+
+### 方式 1: 转换 Markdown 字符串
+
+适合动态生成内容的场景:
+
+```typescript
+import { md2image } from 'md2xhs';
+
+const markdown = `
+# 你好,世界!
+
+这是一个 **Markdown** 转图片的示例。
+
+## 支持的功能
+
+- 支持列表
+- 支持 *斜体* 和 **粗体**
+- 支持 \`行内代码\`
+
+\`\`\`javascript
+// 支持代码块
+console.log('Hello World');
+\`\`\`
+`;
+
+// 转换为小红书格式(3:4 比例)
+await md2image(markdown, {
+  mode: 'xhs',
+  outputPath: './output.png',
+});
+```
+
+### 方式 2: 从文件转换
+
+适合转换现有的 Markdown 文档:
+
+```typescript
+import { md2image } from 'md2xhs';
+
+// 自动生成同名 .png 文件
+await md2image('./README.md', {
+  mode: 'xhs',
+});
+// 生成 README.png
+
+// 或指定输出路径
+await md2image('./docs/guide.md', {
+  mode: 'xhs',
+  outputPath: './images/guide.png',
+});
+```
+
+### 方式 3: 批量转换目录
+
+适合批量处理多个文件:
+
+```typescript
+import { md2imageDir } from 'md2xhs';
+
+// 转换目录中所有 .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>`
+
+```typescript
+interface ConvertResult {
+  imagePath: string;  // 生成的图片路径
+  width: number;      // 图片宽度
+  height: number;     // 图片高度
+}
+```
+
+**示例:**
+
+```typescript
+// 转换字符串
+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[]>`
+
+**示例:**
+
+```typescript
+// 转换单个目录
+const results = await md2imageDir('./docs');
+
+// 递归转换所有子目录
+const allResults = await md2imageDir('./docs', {}, true);
+
+// 使用自定义配置
+await md2imageDir('./docs', {
+  mode: 'xhs',
+  backgroundPreset: 'sunset'
+}, true);
+```
+
+---
+
+### 高级用法: Md2ImageConverter 类
+
+当需要**复用配置**或**批量转换**时,使用 `Md2ImageConverter` 类可以提升性能(复用浏览器实例)。
+
+**完整示例:**
+
+```typescript
+import { Md2ImageConverter } from 'md2xhs';
+
+// 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>`            |
+
+---
+
+## ⚙️ 配置选项详解
+
+### 完整配置接口
+
+```typescript
+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` | 自由模式,高度自适应内容    | 通用场景         |
+
+**使用示例:**
+
+```typescript
+import { md2image, ExportMode } from 'md2xhs';
+
+// 方式 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         |
+
+**使用示例:**
+
+```typescript
+await md2image(markdown, {
+  backgroundPreset: 'sunset',  // 使用暖阳橙预设
+});
+```
+
+### 自定义背景 (customBackground)
+
+如果内置预设不满足需求,可以自定义渐变背景:
+
+```typescript
+await md2image(markdown, {
+  customBackground: {
+    colorStart: '#FF6B6B',  // 起始颜色
+    colorEnd: '#4ECDC4',    // 结束颜色
+    direction: '45deg',     // 渐变方向
+  },
+});
+```
+
+---
+
+## 🎨 扩展功能详解
+
+> **💡 提示**: 所有扩展功能使用**本地资源**,完全离线可用!
+
+### 1. 数学公式 (KaTeX)
+
+默认启用,支持行内和块级公式。
+
+**Markdown 语法:**
+
+```markdown
+行内公式: $E = mc^2$
+
+块级公式:
+$$
+x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
+$$
+```
+
+**禁用方式:**
+
+```typescript
+await md2image(markdown, {
+  extensions: { enableMath: false }
+});
+```
+
+### 2. Mermaid 图表
+
+默认启用,支持流程图、序列图、甘特图等。
+
+**Markdown 语法:**
+
+````markdown
+```mermaid
+graph TD
+    A[开始] --> B{判断}
+    B -->|是| C[执行]
+    B -->|否| D[结束]
+```
+````
+
+**禁用方式:**
+
+```typescript
+await md2image(markdown, {
+  extensions: { enableDiagram: false }
+});
+```
+
+### 3. 卡片语法
+
+使用特殊语法创建彩色卡片块。
+
+**Markdown 语法:**
+
+```markdown
+:::card info
+📘 这是一个信息卡片
+:::
+
+:::card success
+✅ 这是一个成功卡片
+:::
+
+:::card warning
+⚠️ 这是一个警告卡片
+:::
+
+:::card error
+❌ 这是一个错误卡片
+:::
+```
+
+**禁用方式:**
+
+```typescript
+await md2image(markdown, {
+  extensions: { enableCard: false }
+});
+```
+
+---
+
+## 📝 更多示例
+
+### 完整配置示例
+
+结合所有配置选项的完整示例:
+
+```typescript
+import { md2image, ExportMode } from 'md2xhs';
+
+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) 用法
+
+```javascript
+const { md2image } = require('md2xhs');
+
+async function convertMarkdown() {
+  await md2image('# Hello World', {
+    mode: 'xhs',
+    outputPath: './output.png',
+  });
+}
+
+convertMarkdown();
+```
+
+### 错误处理
+
+```typescript
+import { md2image } from 'md2xhs';
+
+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` 值:
+
+```typescript
+await md2image(markdown, {
+  scale: 3,  // 3 倍高清,文件会更大
+});
+```
+
+### 如何更改图片宽度?
+
+```typescript
+await md2image(markdown, {
+  width: 720,  // 默认 640
+});
+```
+
+### 支持哪些 Markdown 语法?
+
+- ✅ 标题 (H1-H6)
+- ✅ 粗体、斜体、删除线
+- ✅ 列表(有序、无序)
+- ✅ 代码块和行内代码
+- ✅ 引用块
+- ✅ 链接和图片
+- ✅ 表格
+- ✅ 数学公式 (KaTeX)
+- ✅ Mermaid 图表
+- ✅ 自定义卡片语法
+
+### 为什么首次运行很慢?
+
+首次运行时 Puppeteer 需要下载 Chromium 浏览器,之后就会很快了。
+
+### 如何在 Docker 中使用?
+
+需要安装 Chromium 依赖:
+
+```dockerfile
+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](https://github.com/xiaolinbaba/Madopic) 的精美样式。
+
+---
+
+## 📄 开源协议
+
+MIT License - 详见 [LICENSE](LICENSE) 文件
+
+本项目基于 [Madopic](https://github.com/xiaolinbaba/Madopic) 进行 Node.js 环境的实现,Madopic 同样采用 MIT 许可证。
+
+---
+
+## 🤝 参与贡献
+
+欢迎提交 Issue 和 Pull Request!
+
+如有问题或建议,请访问 [GitHub Issues](https://github.com/yourusername/md2xhs/issues)。
+
+---
+
+## 🙏 致谢
+
+- [Madopic](https://github.com/xiaolinbaba/Madopic) - 本项目的灵感来源
+- 感谢 [@xiaolinbaba](https://github.com/xiaolinbaba) 的精美设计
+
+---
+
+**⭐️ 如果这个项目对你有帮助,欢迎给个 Star!**

package/dist/assets/auto-render.min.js

@@ -0,0 +1 @@
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("katex")):"function"==typeof define&&define.amd?define(["katex"],t):"object"==typeof exports?exports.renderMathInElement=t(require("katex")):e.renderMathInElement=t(e.katex)}("undefined"!=typeof self?self:this,(function(e){return function(){"use strict";var t={771:function(t){t.exports=e}},r={};function n(e){var i=r[e];if(void 0!==i)return i.exports;var a=r[e]={exports:{}};return t[e](a,a.exports,n),a.exports}n.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return n.d(t,{a:t}),t},n.d=function(e,t){for(var r in t)n.o(t,r)&&!n.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},n.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)};var i={};return function(){n.d(i,{default:function(){return s}});var e=n(771),t=n.n(e),r=function(e,t,r){for(var n=r,i=0,a=e.length;n<t.length;){var o=t[n];if(i<=0&&t.slice(n,n+a)===e)return n;"\\"===o?n++:"{"===o?i++:"}"===o&&i--,n++}return-1},a=/^\\begin{/,o=function(e,t){for(var n,i=[],o=new RegExp("("+t.map((function(e){return e.left.replace(/[-/\\^$*+?.()|[\]{}]/g,"\\$&")})).join("|")+")");-1!==(n=e.search(o));){n>0&&(i.push({type:"text",data:e.slice(0,n)}),e=e.slice(n));var l=t.findIndex((function(t){return e.startsWith(t.left)}));if(-1===(n=r(t[l].right,e,t[l].left.length)))break;var d=e.slice(0,n+t[l].right.length),s=a.test(d)?d:e.slice(t[l].left.length,n);i.push({type:"math",data:s,rawData:d,display:t[l].display}),e=e.slice(n+t[l].right.length)}return""!==e&&i.push({type:"text",data:e}),i},l=function(e,r){var n=o(e,r.delimiters);if(1===n.length&&"text"===n[0].type)return null;for(var i=document.createDocumentFragment(),a=0;a<n.length;a++)if("text"===n[a].type)i.appendChild(document.createTextNode(n[a].data));else{var l=document.createElement("span"),d=n[a].data;r.displayMode=n[a].display;try{r.preProcess&&(d=r.preProcess(d)),t().render(d,l,r)}catch(e){if(!(e instanceof t().ParseError))throw e;r.errorCallback("KaTeX auto-render: Failed to parse `"+n[a].data+"` with ",e),i.appendChild(document.createTextNode(n[a].rawData));continue}i.appendChild(l)}return i},d=function e(t,r){for(var n=0;n<t.childNodes.length;n++){var i=t.childNodes[n];if(3===i.nodeType){for(var a=i.textContent,o=i.nextSibling,d=0;o&&o.nodeType===Node.TEXT_NODE;)a+=o.textContent,o=o.nextSibling,d++;var s=l(a,r);if(s){for(var f=0;f<d;f++)i.nextSibling.remove();n+=s.childNodes.length-1,t.replaceChild(s,i)}else n+=d}else 1===i.nodeType&&function(){var t=" "+i.className+" ";-1===r.ignoredTags.indexOf(i.nodeName.toLowerCase())&&r.ignoredClasses.every((function(e){return-1===t.indexOf(" "+e+" ")}))&&e(i,r)}()}},s=function(e,t){if(!e)throw new Error("No element provided to render");var r={};for(var n in t)t.hasOwnProperty(n)&&(r[n]=t[n]);r.delimiters=r.delimiters||[{left:"$$",right:"$$",display:!0},{left:"\\(",right:"\\)",display:!1},{left:"\\begin{equation}",right:"\\end{equation}",display:!0},{left:"\\begin{align}",right:"\\end{align}",display:!0},{left:"\\begin{alignat}",right:"\\end{alignat}",display:!0},{left:"\\begin{gather}",right:"\\end{gather}",display:!0},{left:"\\begin{CD}",right:"\\end{CD}",display:!0},{left:"\\[",right:"\\]",display:!0}],r.ignoredTags=r.ignoredTags||["script","noscript","style","textarea","pre","code","option"],r.ignoredClasses=r.ignoredClasses||[],r.errorCallback=r.errorCallback||console.error,r.macros=r.macros||{},d(e,r)}}(),i=i.default}()}));