markdown-to-mfuns-json 1.0.0

package/README.md

@@ -0,0 +1,457 @@
+# markdown-to-mfuns-json
+
+将 Markdown 格式的内容转换为喵御宅（Mfuns）定制的 Quill Delta JSON 格式。
+
+适用于：文章正文、视频简介、动态正文、评论正文等场景。
+
+## 安装
+
+```bash
+npm install markdown-to-mfuns-json
+```
+
+```bash
+yarn add markdown-to-mfuns-json
+```
+
+## 快速开始
+
+### ESM (import)
+
+```typescript
+import { markdownToQuillDelta } from "markdown-to-mfuns-json";
+
+const markdown = `
+## 标题
+
+这是一段**粗体**和*斜体*的文字。
+
+- 列表项 1
+- 列表项 2
+`;
+
+const deltaJson = markdownToQuillDelta(markdown);
+console.log(deltaJson);
+// 输出: {"ops":[{"insert":"标题"},{"insert":"\n","attributes":{"header":2}},{"insert":"这是一段"},{"insert":"粗体","attributes":{"bold":true}},{"insert":"和"},{"insert":"斜体","attributes":{"italic":true}},{"insert":"的文字。"},{"insert":"\n"},{"insert":"列表项 1"},{"insert":"\n","attributes":{"list":"bullet"}},{"insert":"列表项 2"},{"insert":"\n","attributes":{"list":"bullet"}}]}
+```
+
+### CommonJS (require)
+
+```javascript
+const { markdownToQuillDelta } = require("markdown-to-mfuns-json");
+
+const markdown = `## Hello World`;
+const deltaJson = markdownToQuillDelta(markdown);
+console.log(deltaJson);
+```
+
+## API
+
+### `markdownToQuillDelta(markdown, options?, uploadOptions?)`
+
+将 Markdown 文本转换为 Quill Delta JSON 字符串。
+
+**参数：**
+
+| 参数            | 类型             | 必填 | 说明                                      |
+| --------------- | ---------------- | ---- | ----------------------------------------- |
+| `markdown`      | `string`         | 是   | Markdown 格式的文本                       |
+| `options`       | `ParserOptions`  | 否   | 解析器配置选项                            |
+| `uploadOptions` | `UploadOptions`  | 否   | 图片上传配置（需要上传图片到 Mfuns 时必填） |
+
+**返回值：**
+
+`Promise<string>` - Quill Delta JSON 格式的字符串
+
+**示例：**
+
+```typescript
+import { markdownToQuillDelta } from "markdown-to-mfuns-json";
+
+// 基础用法（无图片上传）
+const deltaJson = await markdownToQuillDelta("## Hello World");
+
+// 带图片上传（需要登录后的 session token）
+const deltaJson = await markdownToQuillDelta(
+  markdown,
+  {}, // ParserOptions
+  {
+    token: "your-session-token",
+    deviceInfo: {
+      clientType: "web",
+      deviceId: "xxx",
+    },
+  }
+);
+```
+
+---
+
+### `markdownToQuillDeltaObject(markdown, options?, uploadOptions?)`
+
+将 Markdown 文本转换为 Quill Delta 对象（非 JSON 字符串）。
+
+**参数：**
+
+| 参数            | 类型             | 必填 | 说明                                      |
+| --------------- | ---------------- | ---- | ----------------------------------------- |
+| `markdown`      | `string`         | 是   | Markdown 格式的文本                       |
+| `options`       | `ParserOptions`  | 否   | 解析器配置选项                            |
+| `uploadOptions` | `UploadOptions`  | 否   | 图片上传配置（需要上传图片到 Mfuns 时必填） |
+
+**返回值：**
+
+`Promise<QuillDelta>` - Quill Delta 对象
+
+**示例：**
+
+```typescript
+import { markdownToQuillDeltaObject } from "markdown-to-mfuns-json";
+
+const deltaObj = await markdownToQuillDeltaObject("## Hello");
+console.log(deltaObj.ops); // 访问 ops 数组
+```
+
+---
+
+### 空行处理说明
+
+**默认情况下，空行会被跳过，不生成任何 Delta 操作。**
+
+这是因为 Quill Delta 中的空行（`{ insert: "\n" }`）在 Mfuns 平台的某些场景（如文章正文、评论等）可能会导致显示异常或多余的换行。因此默认行为是忽略所有空行。
+
+如果需要保留空行，可以设置 `preserveEmptyLines: true`：
+
+```typescript
+const markdown = `第一行
+
+第二行`;
+
+// 默认：跳过空行
+const result1 = markdownToQuillDelta(markdown);
+// 输出: [{ insert: '第一行' }, { insert: '\n' }, { insert: '第二行' }, { insert: '\n' }]
+
+// 保留空行
+const result2 = markdownToQuillDelta(markdown, { preserveEmptyLines: true });
+// 输出: [{ insert: '第一行' }, { insert: '\n' }, { insert: '\n' }, { insert: '第二行' }, { insert: '\n' }]
+```
+
+---
+
+### `ParserOptions`
+
+解析器配置选项接口。
+
+```typescript
+interface ParserOptions {
+  /**
+   * 是否跳过一级标题（#）
+   * 
+   * **设计原因**：
+   * 文章/视频标题本身就是页面的 H1，正文再次出现 H1 会导致：
+   * 1. SEO 问题 - 搜索引擎难以确定页面核心主题，分散权重
+   * 2. 不符合最佳实践 - 每个页面应只有一个 H1（W3C 和无障碍访问规范）
+   * 3. 喵御宅建议 - 正文不建议使用一级标题
+   * 
+   * @default true
+   */
+  skipH1?: boolean;
+
+  /**
+   * 是否跳过四级及以上标题（####, #####, ######）
+   * 
+   * **设计原因**：
+   * 喵御宅平台只支持 1、2、3 级标题，四级及以上会被忽略
+   * 
+   * @default true
+   */
+  skipHighLevelHeaders?: boolean;
+
+  /**
+   * 是否保留空行
+   * 
+   * **设计原因**：
+   * 默认 false（跳过空行）。Quill Delta 中的空行在喵御宅某些场景
+   * （如文章正文、评论）可能导致排版异常或多余换行
+   * 
+   * @default false
+   */
+  preserveEmptyLines?: boolean;
+}
+```
+
+**示例：**
+
+```typescript
+import { markdownToQuillDelta } from "markdown-to-mfuns-json";
+
+const markdown = `
+# 一级标题（会被跳过）
+## 二级标题
+
+正文内容
+`;
+
+// 默认配置（跳过一级标题）
+const defaultResult = markdownToQuillDelta(markdown);
+
+// 保留一级标题
+const withH1 = markdownToQuillDelta(markdown, { skipH1: false });
+
+// 保留空行
+const withEmptyLines = markdownToQuillDelta(markdown, {
+  preserveEmptyLines: true,
+});
+```
+
+---
+
+### `UploadOptions`
+
+图片上传配置选项接口（用于自动上传图片到喵御宅服务器）。
+
+```typescript
+interface UploadOptions {
+  /**
+   * Redis session token（喵御宅登录后的 session token）
+   * 必须提供才能上传图片到喵御宅服务器
+   */
+  token: string;
+
+  /**
+   * 可选设备信息
+   * 用于上传图片时的设备标识
+   */
+  deviceInfo?: {
+    clientType?: string;
+    deviceId?: string;
+    osName?: string;
+    osVersion?: string;
+    deviceModel?: string;
+  };
+
+  /**
+   * 图片上传失败时的回调
+   * - 'throw': 抛出错误（默认）
+   * - 'skip': 跳过该图片（不插入到结果中）
+   * - 'keep-original': 保留原 URL（base64 图片不支持）
+   */
+  onImageUploadError?: (error: Error, url: string) => 'throw' | 'skip' | 'keep-original';
+}
+```
+
+**图片处理规则：**
+
+1. **提供了 `token`**：
+   - 网络图片 URL（`https://...`）：自动下载并上传到 Mfuns 服务器
+   - Base64 图片：解码并上传到 Mfuns 服务器
+   - 上传成功后，图片 URL 会被替换为 Mfuns 的 CDN 地址
+
+2. **未提供 `token`**：
+   - 网络图片 URL：保留原 URL，不上传
+   - Base64 图片：**抛出错误**（Mfuns 禁止 base64 格式）
+
+**示例：**
+
+```typescript
+import { markdownToQuillDelta } from "markdown-to-mfuns-json";
+
+const markdown = `
+## 带图片的文章
+
+![网络图片](https://example.com/image.png)
+![Base64图片](data:image/png;base64,iVBORw0KGgo...)
+`;
+
+// 自动上传所有图片到 Mfuns
+const deltaJson = await markdownToQuillDelta(
+  markdown,
+  {},
+  {
+    token: "your-session-token",
+    deviceInfo: {
+      clientType: "web",
+      deviceId: "unique-device-id",
+    },
+  }
+);
+```
+
+---
+
+### `uploadImageToMfuns(file, options)`
+
+单独上传图片到喵御宅服务器。如果只需要上传图片而不转换 Markdown，可以使用此函数。
+
+**参数：**
+
+| 参数      | 类型            | 必填 | 说明                          |
+| --------- | --------------- | ---- | ----------------------------- |
+| `file`    | `File \| Blob`  | 是   | 要上传的图片文件              |
+| `options` | `UploadOptions` | 是   | 上传配置（必须包含 `token`）  |
+
+**返回值：**
+
+`Promise<string>` - 上传成功后的图片 URL
+
+**示例：**
+
+```typescript
+import { uploadImageToMfuns } from "markdown-to-mfuns-json";
+
+// 从文件选择器获取 File 对象
+const fileInput = document.getElementById('fileInput') as HTMLInputElement;
+const file = fileInput.files![0];
+
+const imageUrl = await uploadImageToMfuns(file, {
+  token: "your-session-token",
+});
+console.log("上传成功:", imageUrl);
+```
+
+---
+
+### 类型定义
+
+```typescript
+// Delta 操作项
+interface DeltaOp {
+  insert: string | { [key: string]: unknown };
+  attributes?: { [key: string]: unknown };
+}
+
+// Quill Delta 对象
+interface QuillDelta {
+  ops: DeltaOp[];
+}
+```
+
+## 支持的 Markdown 语法
+
+### 块级元素
+
+| Markdown           | 说明     | 输出属性               |
+| ------------------ | -------- | ---------------------- |
+| `## 标题`          | 二级标题 | `{"header": 2}`        |
+| `### 标题`         | 三级标题 | `{"header": 3}`        |
+| `- 项目`           | 无序列表 | `{"list": "bullet"}`   |
+| `1. 项目`          | 有序列表 | `{"list": "ordered"}`  |
+| `\`\`\`code\`\`\`` | 代码块   | `{"code-block": true}` |
+| `---` 或 `***`     | 分割线   | `{"divider": true}`    |
+
+### 行内格式
+
+| Markdown        | 说明     | 输出属性              |
+| --------------- | -------- | --------------------- |
+| `**粗体**`      | 粗体     | `{"bold": true}`      |
+| `*斜体*`        | 斜体     | `{"italic": true}`    |
+| `~~删除线~~`    | 删除线   | `{"strike": true}`    |
+| `<u>下划线</u>` | 下划线   | `{"underline": true}` |
+| `[链接](url)`   | 链接     | `{"link": "url"}`     |
+| `![图片](url)`  | 图片     | `{"image": "url"}`    |
+| `` `代码` ``    | 行内代码 | `{"code": true}`      |
+
+### 不支持的语法
+
+以下 Markdown 语法会被跳过或作为普通文本处理：
+
+- 一级标题 `# `（默认跳过，可通过 `skipH1: false` 开启）
+- 四级及以上标题 `#### `（默认跳过）
+- 引用块 `> `
+- 表格
+- 任务列表 `- [ ]`
+
+### 图片格式支持
+
+| 类型        | 说明                      | 处理方式                          |
+| ----------- | ------------------------- | --------------------------------- |
+| 网络图片    | `https://example.com/xxx.png` | 提供 token 时自动下载上传，否则保留原 URL |
+| Base64 图片 | `data:image/png;base64,...`   | 必须提供 token，否则报错          |
+
+支持的图片格式：`jpg`, `jpeg`, `png`, `gif`, `webp`, `bmp`, `svg`
+
+最大支持：20MB
+
+## 完整示例
+
+```typescript
+import {
+  markdownToQuillDelta,
+  markdownToQuillDeltaObject,
+} from "markdown-to-mfuns-json";
+
+const markdown = `
+## 文章标题
+
+这是一篇**示例文章**，包含多种格式：
+
+### 列表
+
+- 无序列表项 1
+- 无序列表项 2
+
+1. 有序列表项 1
+2. 有序列表项 2
+
+### 格式
+
+- **粗体文字**
+- *斜体文字*
+- ~~删除线~~
+- <u>下划线</u>
+- [链接](https://example.com)
+- 行内代码 \`console.log('hello')\`
+
+### 代码块
+
+\`\`\`javascript
+function hello() {
+  console.log('Hello World');
+}
+\`\`\`
+
+---
+
+![示例图片](https://example.com/image.png)
+`;
+
+async function main() {
+  // 基础用法（无图片上传）
+  const deltaJson = await markdownToQuillDelta(markdown);
+  console.log("JSON:", deltaJson);
+
+  // 获取对象
+  const deltaObj = await markdownToQuillDeltaObject(markdown);
+  console.log("对象:", deltaObj);
+  console.log("操作数:", deltaObj.ops.length);
+
+  // 带图片上传（需要登录后的 session token）
+  const deltaWithUpload = await markdownToQuillDelta(
+    markdown,
+    {}, // ParserOptions
+    {
+      token: "your-session-token-here",
+    }
+  );
+  console.log("带上传的 JSON:", deltaWithUpload);
+}
+
+main();
+```
+
+## 应用场景
+
+本库专为喵御宅（Mfuns）平台设计，可用于：
+
+1. **文章正文** - 将用户输入的 Markdown 转换为平台文章格式
+2. **视频简介** - 转换视频描述内容
+3. **动态正文** - 转换用户动态/帖子内容
+4. **评论正文** - 转换评论内容
+
+## Node.js 版本要求
+
+- Node.js >= 16.0.0
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,6 @@
+// 导出核心函数
+const {  markdownToQuillDelta, markdownToQuillDeltaObject,  } = require('./parser.cjs');
+module.exports = {  markdownToQuillDelta, markdownToQuillDeltaObject,  };
+// 导出图片上传相关函数
+const {  uploadImageToMfuns, processImageUrl, isBase64Image, isImageUrl,  } = require('./upload.cjs');
+module.exports = {  uploadImageToMfuns, processImageUrl, isBase64Image, isImageUrl,  };

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+export type { DeltaOp, QuillDelta, InlineParseResult, ParserOptions, UploadOptions, DeviceInfo, ImageUploadErrorHandler, InlineFormat, BlockElement, } from './types.mjs';
+export { markdownToQuillDelta, markdownToQuillDeltaObject, } from './parser.mjs';
+export { uploadImageToMfuns, processImageUrl, isBase64Image, isImageUrl, type DeviceInfo as UploadDeviceInfo, } from './upload.mjs';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { DeltaOp, QuillDelta, InlineParseResult, ParserOptions, UploadOptions, DeviceInfo, ImageUploadErrorHandler, InlineFormat, BlockElement, } from './types';
+export { markdownToQuillDelta, markdownToQuillDeltaObject, } from './parser';
+export { uploadImageToMfuns, processImageUrl, isBase64Image, isImageUrl, type DeviceInfo as UploadDeviceInfo, } from './upload';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,OAAO,EACP,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,UAAU,EACV,uBAAuB,EACvB,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,UAAU,EACV,KAAK,UAAU,IAAI,gBAAgB,GACpC,MAAM,aAAa,CAAC"}

package/dist/index.mjs

@@ -0,0 +1,4 @@
+// 导出核心函数
+export { markdownToQuillDelta, markdownToQuillDeltaObject, } from './parser.mjs';
+// 导出图片上传相关函数
+export { uploadImageToMfuns, processImageUrl, isBase64Image, isImageUrl, } from './upload.mjs';