# markdown-doc-gen 中文文档 规范地址：https://npmcn.com/package/markdown-doc-gen/ 版本：0\.7\.0 npm 元数据更新时间：2026-11-03T23:58:22.706Z 中文译文更新时间：2026-11-04T03:18:10.435Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/markdown-doc-gen 原文对照：https://npmcn.com/package/markdown-doc-gen/?lang=original 项目主页：https://dhurtado.dev/ ## 关键信息（来自 npm 元数据） - 包体积（解压后）：668 kB，11 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：6 个 - 首次发布：2026-11-03T23:57:06.493Z - 最新版本发布：2026-11-03T23:58:22.552Z - 已发布版本数：2（近 12 个月 2 个） ## 中文简介 通用Markdown处理器和多格式文档生成器，用于Web， Word （DOCX）和PowerPoint （PPTX）。 ## 安装 ```sh npm install markdown-doc-gen ``` 也可以使用：`pnpm add markdown-doc-gen`、`yarn add markdown-doc-gen`、`bun add markdown-doc-gen` ## README # 降价文件生成器(`markdown-doc-gen`） 一个通用的，与框架无关的Markdown处理和多格式文档生成库 **浏览器** 和 **node . js** 环境。 目前可用的输出： - **网页(HTML)**：具有可定制样式和CSS自定义属性的语义HTML。 - **词(docx)**：完全可编辑的Microsoft Word文档 `docx`。 - **幻灯片(.pptx)**：由PptxGenJS提供支持的可编辑幻灯片。 计划及未来目标： - **PDF**计划于 [任务4.3](https://npmcn.com/package/markdown-doc-gen/TASKS%20V1.md);适配器还不可用。 * * * ## 🌟主要特性 - **同构(通用)**：在浏览器客户端（Angular, React, Vue, Svelte, Vanilla JS）和服务器端运行时（Node.js, Bun, Deno）中无缝运行。 - **框架不可知**：零依赖于任何UI框架。 - **AST-Driven架构**：由 `marked.lexer` 一个解耦的 **中间文档模型（IR）** 由支持的输出适配器共享。 - **统一设计令牌(`DocTheme`）**：使用类型化JSON/TypeScript设计令牌在当前支持的输出中一致地配置颜色、字体和间距。 - **零依赖HTML引擎**快速，纯TypeScript语义HTML渲染器。 - **开发者游乐场和测试套件**： Vitest的交互式浏览器平台和全面测试覆盖率。 * * * ## ️架构与管道 ``` [Markdown String] [Custom Theme (Optional)] │ │ ▼ ▼ 1. Lexer (marked.lexer) Theme Definition │ (Defaults + Overrides) ▼ │ [Raw Tokens AST] │ │ │ ▼ │ 2. Intermediate Document Model (IR) │ • Pure semantic AST normalization │ │ │ └────────────────────┬────────────────────┘ │ ▼ 3. Theme Resolution & Style Binding • Binds design tokens to the semantic tree │ ┌──────────────────────┼──────────────────────┐ ▼ ▼ ▼ 4a. HTML Adapter 4b. DOCX Adapter 4c. PPTX Adapter (available) (available) (available) │ │ │ ▼ ▼ ▼ [HTML] [DOCX] [PPTX] Planned: PDF adapter (`pdfmake`, Task 4.3) ``` 完整的技术参数请参见 [ARCHITECTURE.md](https://npmcn.com/package/markdown-doc-gen/ARCHITECTURE.md)。 * * * ## 📦快速入门（概念用法） ### 1\. Web HTML渲染 ```typescript import { parseToAst, normalizeAst, renderToHtml } from 'markdown-doc-gen'; const ast = parseToAst('# Hello World\nThis is **Markdown** rendered to semantic HTML.'); const ir = normalizeAst(ast); // Fully self-contained: embeds theme variables and base styles automatically const html = renderToHtml(ir, { theme: { colors: { primary: '#1e3a5f', text: '#334155' } } }); ``` ### 2\. PDF文件生成（计划） **技术:** `pdfmake` (计划)。 **架构:** 本机适配器将把IR直接映射到 `pdfmake` 文档定义。它的流布局将处理换行和分页，而无需将HTML转换为PDF。 **计划能力:** - 主题映射排版、颜色、间距、标题、段落、列表、代码块、块引号、表格和图像。 - 页面大小、方向、页边距、分页符和页面背景。 - 从数据uri、本地路径或自定义解析器进行图像解析。 - 浏览器 `Blob` 输出和Node.js `Buffer` 输出。 **状态:** 计划在 [任务4.3](https://npmcn.com/package/markdown-doc-gen/TASKS%20V1.md)． 适配器及其公共API尚未实现。 ### 3\. Word （.docx）文档生成 ```typescript import { parseToAst, normalizeAst, renderDocxToBlob, renderDocxToBuffer } from 'markdown-doc-gen'; const ir = normalizeAst(parseToAst(markdown)); // Browser: returns a Blob that can be downloaded by the host application const docxBlob = await renderDocxToBlob(ir); // Node.js: returns the DOCX bytes as a Buffer const docxBuffer = await renderDocxToBuffer(ir); ``` ### 4\. ppt （.pptx）一代 PptxGenJS直接从IR生成可编辑的ppt原生幻灯片。 ```typescript import { renderPptxToBlob, renderPptxToBuffer } from 'markdown-doc-gen'; const ir = normalizeAst(parseToAst(markdown)); const pptxBlob = await renderPptxToBlob(ir); const pptxBuffer = await renderPptxToBuffer(ir); ``` - 每一个 `` 宣言开始幻灯片；前导声明配置第一张幻灯片。 - 如果没有页面声明，文档将放在一张幻灯片上。 - 幻灯片默认为宽屏16:9。布局和内容页边距可以通过 `RenderPptxOptions`。 - 内容不会跨幻灯片分割或自动缩小以适应。作者负责使其适应每张幻灯片。 - 页面背景、图像、主题样式和浏览器 `Blob` / node . js `Buffer` 支持输出。 - 内联图像保留其宽高比，默认情况下宽度限制为5.5英寸，可用幻灯片内容宽度和240pt高。 `maxImageWidth` 以英寸为单位设置宽度限制；源像素在没有升级的情况下被解释为每英寸72像素。 - 新的导出规范了PptxGenJS幻灯片XML，包括富文本段落属性和唯一的表/形状id。 * * * ## 📑页面，背景和页边距 用HTML注释声明页面边界及其可选的背景图像和内容边距： ```markdown # Cover content # Next page content ``` - `bg-image` 适用于整个页面表面，居中和缩放 `cover` 同时保留图像比例。它独立于内容页边距；页边距不会缩小或偏移背景。 - `margin` 仅控制内容区域。它接受一到四种物理测量 `pt`， `mm`， `cm`,或 `in`，并使用CSS速记顺序。 - 文档开头的page指令配置第一页或幻灯片，而不添加空页。后来的指令开始新的页面或幻灯片。 - HTML、DOCX和PPTX目前支持页面背景和页边距。PDF已规划。 * * * ## 🎨主题定制(`DocTheme`） Style当前支持的输出与单一类型配置一致： ```typescript import type { DocTheme } from 'markdown-doc-gen'; const customTheme: DocTheme = { colors: { primary: '#0f766e', // Headings, links, accent borders text: '#1e293b', // Paragraph and list body text codeBg: '#0f172a', // Dark background for code blocks codeText: '#f8fafc', // Code font color cardBg: '#f8fafc', // Blockquote background border: '#e2e8f0' // Divider lines & table borders }, typography: { fontFamily: 'Segoe UI', codeFontFamily: 'Consolas', baseFontSize: 11 } }; ``` * * * ## 🧪测试与互动游乐场 - **互动网页游乐场**:跑 `npm run dev:playground` 测试Markdown解析、实时HTML呈现和DOCX/PPTX下载（热重新加载）。看到 [PLAYGROUND.md](https://npmcn.com/package/markdown-doc-gen/PLAYGROUND.md)。 - **自动化测试**:跑 `npm test` 来执行完整的测试套件 **轻快地**。 * * * ## 📄文档链接 - [ARCHITECTURE.md](https://npmcn.com/package/markdown-doc-gen/ARCHITECTURE.md) -系统架构，IR设计和技术决策。 - [PLAYGROUND.md](https://npmcn.com/package/markdown-doc-gen/PLAYGROUND.md) -手动验证线束和浏览器平台规范。 * * * ## 📜许可证 麻省理工学院的许可。 ## 作者 [Duvan Hurtado](https://dhurtado.dev/) ## 常见问题 ### markdown-doc-gen 是什么？ 通用Markdown处理器和多格式文档生成器，用于Web， Word （DOCX）和PowerPoint （PPTX）。 ### 如何安装 markdown-doc-gen？ 在项目目录运行 npm install markdown-doc-gen，或使用 pnpm add / yarn add / bun add。 ### markdown-doc-gen 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### markdown-doc-gen 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### markdown-doc-gen 可以商用吗？ markdown-doc-gen 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### markdown-doc-gen 还在维护吗？ 最新版本 0\.7\.0 发布于 2026/11/04（1 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。