word2img-mcp

# imgkit/wkhtmltopdf 渲染方案使用指南 ## 🎯 概述 成功实现了基于 `imgkit + wkhtmltopdf` 的 Markdown 渲染方案，这是一个高质量的 HTML 到图片转换解决方案。 ## ✨ 特性 ### 🚀 核心功能 - **HTML 渲染**: 将 Markdown 转换为结构化 HTML，再通过 wkhtmltopdf 渲染为图片 - **自定义样式**: 完全的 CSS 样式控制，支持复杂布局和设计 - **高质量输出**: wkhtmltopdf 提供专业级别的渲染质量 - **中文支持**: 完美支持中文字体和排版 ### 🎨 样式特性 - 自定义背景色、文字色、强调色 - 丰富的字体选项（字体族、大小、行高） - 多种对齐方式（居中、左对齐、右对齐） - 标题缩放和阴影效果 - 表格样式和代码块高亮 - 水印功能 ### 📋 支持的 Markdown 语法 - 标题 (H1-H6) - 段落和文本格式化（粗体、斜体） - 列表（有序、无序） - 表格 - 代码块和行内代码 - 引用块 - 水平分割线 - 链接 ## 🔧 安装与配置 ### 1. 安装 Python 依赖 ```bash # 使用 uv 安装 uv add imgkit markdown # 或使用 pip 安装 pip install imgkit markdown ``` ### 2. 安装 wkhtmltopdf #### Windows 1. 访问 [wkhtmltopdf 官网](https://wkhtmltopdf.org/downloads.html) 2. 下载 Windows 版本安装包 3. 安装到默认路径（通常是 `C:\Program Files\wkhtmltopdf\`） 4. 将安装路径添加到系统 PATH 环境变量 #### macOS ```bash # 使用 Homebrew brew install wkhtmltopdf # 或下载安装包 # https://wkhtmltopdf.org/downloads.html ``` #### Linux (Ubuntu/Debian) ```bash sudo apt-get update sudo apt-get install wkhtmltopdf ``` #### Linux (CentOS/RHEL) ```bash sudo yum install wkhtmltopdf # 或 sudo dnf install wkhtmltopdf ``` ### 3. 验证安装 ```bash # 检查 wkhtmltoimage 是否可用 wkhtmltoimage --version ``` ## 🚀 使用方法 ### 1. 基础使用 ```python from word2img_mcp.render import RenderOptions, MarkdownRenderer # 创建渲染选项 options = RenderOptions( width=1200, height=1600, background=(255, 255, 255), # 白色背景 text_color=(0, 0, 0), # 黑色文字 accent_color=(70, 130, 180), # 钢蓝色强调 align="left", font_size=16, output_format="png" ) # Markdown 内容 markdown_text = """ # 标题示例 这是一个 **加粗文字** 和 *斜体文字* 的示例。 ## 列表示例 - 项目 1 - 项目 2 - 项目 3 ## 表格示例 | 列 1 | 列 2 | 列 3 | |------|------|------| | A | B | C | | 1 | 2 | 3 | """ # 渲染 renderer = MarkdownRenderer() output_path = renderer.render(markdown_text, options) print(f"图片已生成: {output_path}") ``` ### 2. 高级配置 ```python # 创建高级渲染选项 advanced_options = RenderOptions( width=1400, height=1800, background=(248, 249, 250), # 浅灰背景 text_color=(33, 37, 41), # 深灰文字 accent_color=(13, 110, 253), # 蓝色强调 align="center", font_family="'Microsoft YaHei', 'PingFang SC', Arial, sans-serif", font_size=18, line_height=1.8, header_scale=1.6, shadow=True, # 标题阴影 watermark=True, # 水印 watermark_text="Generated by imgkit", output_format="jpg" ) ``` ### 3. MCP 服务使用 ```python # 通过 MCP 接口使用 import asyncio from word2img_mcp.mcp_app import server # 启动 MCP 服务器 # uv run python -m word2img_mcp.server ``` ## 🔍 故障排除 ### 常见问题 #### 1. "No wkhtmltoimage executable found" **问题**: wkhtmltopdf 未安装或不在 PATH 中 **解决方案**: - 确保已安装 wkhtmltopdf - 检查安装路径是否在系统 PATH 中 - Windows 用户检查是否需要重启命令行 #### 2. 中文字体显示问题 **问题**: 中文字符显示为方框或乱码 **解决方案**: - 确保系统安装了中文字体 - 在 `font_family` 中指定正确的中文字体 - Windows: "Microsoft YaHei" - macOS: "PingFang SC" - Linux: 安装 `fonts-wqy-zenhei` 等中文字体包 #### 3. 渲染超时 **问题**: 复杂内容渲染时间过长 **解决方案**: - 适当增加超时时间 - 简化内容结构 - 检查网络连接（如果内容包含外部资源） #### 4. 图片质量问题 **问题**: 输出图片模糊或质量不佳 **解决方案**: - 增加输出尺寸 - 调整 `quality` 参数 - 使用 PNG 格式获得更好质量 ## 📊 性能对比 | 后端 | 质量 | 速度 | 功能性 | 依赖复杂度 | |------|------|------|--------|------------| | imgkit/wkhtmltopdf | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | | markdown-pdf | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | | PIL 备选 | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ## 🎨 样式定制 ### CSS 样式系统 imgkit 后端使用完整的 CSS 样式系统，支持： - 字体和排版 - 颜色和背景 - 边距和间距 - 边框和阴影 - 伪元素和动画（静态渲染） ### 自定义主题 可以通过修改 `_generate_css` 方法创建自定义主题： ```python def create_dark_theme_options(): return RenderOptions( background=(33, 37, 41), # 深色背景 text_color=(248, 249, 250), # 浅色文字 accent_color=(108, 117, 125), # 灰色强调 # ... 其他选项 ) ``` ## 📚 技术细节 ### 渲染流程 1. **Markdown 解析**: 使用 `python-markdown` 将 Markdown 转换为 HTML 2. **样式注入**: 根据 `RenderOptions` 生成对应的 CSS 样式 3. **HTML 组装**: 将内容和样式组合成完整的 HTML 文档 4. **图片渲染**: 使用 wkhtmltoimage 将 HTML 渲染为图片 5. **文件输出**: 保存到指定路径 ### 扩展功能 - **表格支持**: 自动处理复杂表格布局 - **代码高亮**: 支持多种编程语言语法高亮 - **响应式设计**: 自适应不同尺寸要求 - **水印系统**: 灵活的水印位置和样式 ## 🔮 未来改进 ### 计划功能 - 主题预设系统 - 更多输出格式支持 - 性能优化 - 批量处理功能 - 自定义字体加载 ### 贡献指南 欢迎提交 Issue 和 Pull Request 来改进这个项目！ ## 📄 许可证 本项目使用与主项目相同的许可证。 --- **享受使用 imgkit/wkhtmltopdf 带来的高质量 Markdown 渲染体验！** 🎉