降价文件生成器(markdown-doc-gen）
一个通用的，与框架无关的Markdown处理和多格式文档生成库 浏览器 和 node . js 环境。
目前可用的输出：
- 网页(HTML)：具有可定制样式和CSS自定义属性的语义HTML。
- 词(docx)：完全可编辑的Microsoft Word文档
docx。 - 幻灯片(.pptx)：由PptxGenJS提供支持的可编辑幻灯片。
计划及未来目标：
- PDF计划于 任务4.3;适配器还不可用。
🌟主要特性
- 同构(通用)：在浏览器客户端（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。
📦快速入门（概念用法）
1. Web HTML渲染
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.jsBuffer输出。
状态: 计划在 任务4.3． 适配器及其公共API尚未实现。
3. Word （.docx）文档生成
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原生幻灯片。
import { renderPptxToBlob, renderPptxToBuffer } from 'markdown-doc-gen';
const ir = normalizeAst(parseToAst(markdown));
const pptxBlob = await renderPptxToBlob(ir);
const pptxBuffer = await renderPptxToBuffer(ir);
- 每一个
<!-- page -->宣言开始幻灯片；前导声明配置第一张幻灯片。 - 如果没有页面声明，文档将放在一张幻灯片上。
- 幻灯片默认为宽屏16:9。布局和内容页边距可以通过
RenderPptxOptions。 - 内容不会跨幻灯片分割或自动缩小以适应。作者负责使其适应每张幻灯片。
- 页面背景、图像、主题样式和浏览器
Blob/ node . jsBuffer支持输出。 - 内联图像保留其宽高比，默认情况下宽度限制为5.5英寸，可用幻灯片内容宽度和240pt高。
maxImageWidth以英寸为单位设置宽度限制；源像素在没有升级的情况下被解释为每英寸72像素。 - 新的导出规范了PptxGenJS幻灯片XML，包括富文本段落属性和唯一的表/形状id。
📑页面，背景和页边距
用HTML注释声明页面边界及其可选的背景图像和内容边距：
<!-- page bg-image="./assets/cover.jpg" margin="36pt 48pt" -->
# Cover content
<!-- page margin="20mm 25mm" -->
# Next page content
bg-image适用于整个页面表面，居中和缩放cover同时保留图像比例。它独立于内容页边距；页边距不会缩小或偏移背景。margin仅控制内容区域。它接受一到四种物理测量pt，mm，cm,或in，并使用CSS速记顺序。- 文档开头的page指令配置第一页或幻灯片，而不添加空页。后来的指令开始新的页面或幻灯片。
- HTML、DOCX和PPTX目前支持页面背景和页边距。PDF已规划。
🎨主题定制(DocTheme）
Style当前支持的输出与单一类型配置一致：
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。 - 自动化测试:跑
npm test来执行完整的测试套件 轻快地。
📄文档链接
- ARCHITECTURE.md -系统架构，IR设计和技术决策。
- PLAYGROUND.md -手动验证线束和浏览器平台规范。
📜许可证
麻省理工学院的许可。