docs: update documentation for Export to Word plugin (v0.2.0)
This commit is contained in:
fujie
43
.github/copilot-instructions.md
vendored
43
.github/copilot-instructions.md
vendored
@@ -798,6 +798,49 @@ For iframe plugins to access parent document theme information, users need to co
|
|||||||
- [ ] 使用 logging 而非 print
|
- [ ] 使用 logging 而非 print
|
||||||
- [ ] 测试双语界面
|
- [ ] 测试双语界面
|
||||||
- [ ] **一致性检查 (Consistency Check)**:
|
- [ ] **一致性检查 (Consistency Check)**:
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 高级开发模式 (Advanced Development Patterns)
|
||||||
|
|
||||||
|
### 混合服务端-客户端生成 (Hybrid Server-Client Generation)
|
||||||
|
|
||||||
|
对于需要复杂前端渲染（如 Mermaid 图表、ECharts）但最终生成文件（如 DOCX、PDF）的场景，建议采用混合模式：
|
||||||
|
|
||||||
|
1. **服务端 (Python)**：
|
||||||
|
* 处理文本解析、Markdown 转换、文档结构构建。
|
||||||
|
* 为复杂组件生成**占位符**（如带有特定 ID 或元数据的图片/文本块）。
|
||||||
|
* 将半成品文件（如 Base64 编码的 ZIP/DOCX）发送给前端。
|
||||||
|
|
||||||
|
2. **客户端 (JavaScript)**：
|
||||||
|
* 在浏览器中加载半成品文件（使用 JSZip 等库）。
|
||||||
|
* 利用浏览器能力渲染复杂组件（如 `mermaid.render`）。
|
||||||
|
* 将渲染结果（SVG/PNG）回填到占位符位置。
|
||||||
|
* 触发最终文件的下载。
|
||||||
|
|
||||||
|
**优势**：
|
||||||
|
* 无需在服务端安装 Headless Browser（如 Puppeteer），降低部署复杂度。
|
||||||
|
* 利用用户浏览器的计算能力。
|
||||||
|
* 支持动态、交互式内容的静态化导出。
|
||||||
|
|
||||||
|
### 原生 Word 公式支持 (Native Word Math Support)
|
||||||
|
|
||||||
|
对于需要生成高质量数学公式的 Word 文档，推荐使用 `latex2mathml` + `mathml2omml` 组合：
|
||||||
|
|
||||||
|
1. **LaTeX -> MathML**: 使用 `latex2mathml` 将 LaTeX 字符串转换为标准 MathML。
|
||||||
|
2. **MathML -> OMML**: 使用 `mathml2omml` 将 MathML 转换为 Office Math Markup Language (OMML)。
|
||||||
|
3. **插入 Word**: 将 OMML XML 插入到 `python-docx` 的段落中。
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 示例代码
|
||||||
|
from latex2mathml.converter import convert as latex2mathml
|
||||||
|
from mathml2omml import convert as mathml2omml
|
||||||
|
|
||||||
|
def add_math(paragraph, latex_str):
|
||||||
|
mathml = latex2mathml(latex_str)
|
||||||
|
omml = mathml2omml(mathml)
|
||||||
|
# ... 插入 OMML 到 paragraph._element ...
|
||||||
|
```
|
||||||
- [ ] 更新 `README.md` 插件列表
|
- [ ] 更新 `README.md` 插件列表
|
||||||
- [ ] 更新 `README_CN.md` 插件列表
|
- [ ] 更新 `README_CN.md` 插件列表
|
||||||
- [ ] 更新/创建 `docs/` 下的对应文档
|
- [ ] 更新/创建 `docs/` 下的对应文档
|
||||||
|
|||||||
@@ -1,9 +1,9 @@
|
|||||||
# Export to Word
|
# Export to Word
|
||||||
|
|
||||||
<span class="category-badge action">Action</span>
|
<span class="category-badge action">Action</span>
|
||||||
<span class="version-badge">v0.1.0</span>
|
<span class="version-badge">v0.2.0</span>
|
||||||
|
|
||||||
Export chat conversations to Word (.docx) with Markdown formatting, syntax highlighting, and smarter filenames.
|
Export conversation to Word (.docx) with **syntax highlighting**, **native math equations**, **Mermaid diagrams**, **citations**, and **enhanced table formatting**.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -13,11 +13,17 @@ The Export to Word plugin converts chat messages from Markdown to a polished Wor
|
|||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- :material-file-word-box: **DOCX Export**: Generate Word files with one click
|
- :material-file-word-box: **One-Click Export**: Adds an "Export to Word" action button to the chat.
|
||||||
- :material-format-bold: **Rich Markdown Support**: Headings, bold/italic, lists, tables
|
- :material-format-bold: **Markdown Conversion**: Converts Markdown syntax to Word formatting (headings, bold, italic, code, tables, lists).
|
||||||
- :material-code-tags: **Syntax Highlighting**: Pygments-powered code blocks
|
- :material-code-tags: **Syntax Highlighting**: Code blocks are highlighted with Pygments (supports 500+ languages).
|
||||||
- :material-format-quote-close: **Styled Blockquotes**: Left-border gray quote styling
|
- :material-sigma: **Native Math Equations**: LaTeX math (`$$...$$`, `\[...\]`, `$...$`, `\(...\)`) converted to editable Word equations.
|
||||||
- :material-file-document-outline: **Smart Filenames**: Configurable title source (Chat Title, AI Generated, or Markdown Title)
|
- :material-graph: **Mermaid Diagrams**: Mermaid flowcharts and sequence diagrams rendered as images in the document.
|
||||||
|
- :material-book-open-page-variant: **Citations & References**: Auto-generates a References section from OpenWebUI sources with clickable citation links.
|
||||||
|
- :material-brain-off: **Reasoning Stripping**: Automatically removes AI thinking blocks (`<think>`, `<analysis>`) from exports.
|
||||||
|
- :material-table: **Enhanced Tables**: Smart column widths, column alignment (`:---`, `---:`, `:---:`), header row repeat across pages.
|
||||||
|
- :material-format-quote-close: **Blockquote Support**: Markdown blockquotes are rendered with left border and gray styling.
|
||||||
|
- :material-translate: **Multi-language Support**: Properly handles both Chinese and English text.
|
||||||
|
- :material-file-document-outline: **Smarter Filenames**: Configurable title source (Chat Title, AI Generated, or Markdown Title).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -26,8 +32,13 @@ The Export to Word plugin converts chat messages from Markdown to a polished Wor
|
|||||||
You can configure the following settings via the **Valves** button in the plugin settings:
|
You can configure the following settings via the **Valves** button in the plugin settings:
|
||||||
|
|
||||||
| Valve | Description | Default |
|
| Valve | Description | Default |
|
||||||
| :------------- | :------------------------------------------------------------------------------------------ | :----------- |
|
| :--- | :--- | :--- |
|
||||||
| `TITLE_SOURCE` | Source for document title/filename. Options: `chat_title`, `ai_generated`, `markdown_title` | `chat_title` |
|
| `TITLE_SOURCE` | Source for document title/filename. Options: `chat_title`, `ai_generated`, `markdown_title` | `chat_title` |
|
||||||
|
| `MERMAID_JS_URL` | URL for the Mermaid.js library (for diagram rendering). | `https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js` |
|
||||||
|
| `MERMAID_PNG_SCALE` | Scale factor for Mermaid PNG generation (Resolution). Higher = clearer but larger file size. | `3.0` |
|
||||||
|
| `MERMAID_DISPLAY_SCALE` | Scale factor for Mermaid visual size in Word. >1.0 to enlarge, <1.0 to shrink. | `1.5` |
|
||||||
|
| `MERMAID_OPTIMIZE_LAYOUT` | Automatically convert LR (Left-Right) flowcharts to TD (Top-Down) for better fit. | `True` |
|
||||||
|
| `MERMAID_CAPTIONS_ENABLE` | Enable/disable figure captions for Mermaid diagrams. | `True` |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -47,31 +58,37 @@ You can configure the following settings via the **Valves** button in the plugin
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Supported Markdown
|
## Supported Markdown Syntax
|
||||||
|
|
||||||
| Syntax | Word Result |
|
| Syntax | Word Result |
|
||||||
| :---------------------------------- | :----------------------------- |
|
| :--- | :--- |
|
||||||
| `# Heading 1` to `###### Heading 6` | Heading levels 1-6 |
|
| `# Heading 1` to `###### Heading 6` | Heading levels 1-6 |
|
||||||
| `**bold**` / `__bold__` | Bold text |
|
| `**bold**` or `__bold__` | Bold text |
|
||||||
| `*italic*` / `_italic_` | Italic text |
|
| `*italic*` or `_italic_` | Italic text |
|
||||||
| `***bold italic***` | Bold + Italic |
|
| `***bold italic***` | Bold + Italic |
|
||||||
| `` `inline code` `` | Monospace with gray background |
|
| `` `inline code` `` | Monospace with gray background |
|
||||||
| <code>``` code block ```</code> | Syntax-highlighted code block |
|
| ` ``` code block ``` ` | **Syntax highlighted** code block |
|
||||||
| `> blockquote` | Left-bordered gray italic text |
|
| `> blockquote` | Left-bordered gray italic text |
|
||||||
| `[link](url)` | Blue underlined link |
|
| `[link](url)` | Blue underlined link text |
|
||||||
| `~~strikethrough~~` | Strikethrough |
|
| `~~strikethrough~~` | Strikethrough text |
|
||||||
| `- item` / `* item` | Bullet list |
|
| `- item` or `* item` | Bullet list |
|
||||||
| `1. item` | Numbered list |
|
| `1. item` | Numbered list |
|
||||||
| Markdown tables | Grid table |
|
| Markdown tables | **Enhanced table** with smart widths |
|
||||||
| `---` / `***` | Horizontal rule |
|
| `---` or `***` | Horizontal rule |
|
||||||
|
| `$$LaTeX$$` or `\[LaTeX\]` | **Native Word equation** (display) |
|
||||||
|
| `$LaTeX$` or `\(LaTeX\)` | **Native Word equation** (inline) |
|
||||||
|
| ` ```mermaid ... ``` ` | **Mermaid diagram** as image |
|
||||||
|
| `[1]` citation markers | **Clickable links** to References |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
!!! note "Prerequisites"
|
!!! note "Prerequisites"
|
||||||
- `python-docx==1.1.2` (document generation)
|
- `python-docx==1.1.2` - Word document generation
|
||||||
- `Pygments>=2.15.0` (syntax highlighting, optional but recommended)
|
- `Pygments>=2.15.0` - Syntax highlighting
|
||||||
|
- `latex2mathml` - LaTeX to MathML conversion
|
||||||
|
- `mathml2omml` - MathML to Office Math (OMML) conversion
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,9 +1,9 @@
|
|||||||
# Export to Word（导出为 Word）
|
# Export to Word（导出为 Word）
|
||||||
|
|
||||||
<span class="category-badge action">Action</span>
|
<span class="category-badge action">Action</span>
|
||||||
<span class="version-badge">v0.1.0</span>
|
<span class="version-badge">v0.2.0</span>
|
||||||
|
|
||||||
将聊天记录按 Markdown 格式导出为 Word (.docx)，支持语法高亮、引用样式和更智能的文件命名。
|
将当前对话导出为完美格式的 Word 文档，支持**代码语法高亮**、**原生数学公式**、**Mermaid 图表**、**引用资料**以及**增强表格**渲染。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -13,11 +13,17 @@ Export to Word 插件会把聊天消息从 Markdown 转成精致的 Word 文档
|
|||||||
|
|
||||||
## 功能特性
|
## 功能特性
|
||||||
|
|
||||||
- :material-file-word-box: **DOCX 导出**：一键生成 Word 文件
|
- :material-file-word-box: **一键导出**：在聊天界面添加"导出为 Word"动作按钮。
|
||||||
- :material-format-bold: **丰富 Markdown 支持**：标题、粗斜体、列表、表格
|
- :material-format-bold: **Markdown 转换**：将 Markdown 语法转换为 Word 格式（标题、粗体、斜体、代码、表格、列表）。
|
||||||
- :material-code-tags: **语法高亮**：Pygments 驱动的代码块上色
|
- :material-code-tags: **代码语法高亮**：使用 Pygments 库为代码块添加语法高亮（支持 500+ 种语言）。
|
||||||
- :material-format-quote-close: **引用样式**：左侧边框的灰色斜体引用
|
- :material-sigma: **原生数学公式**：LaTeX 公式（`$$...$$`、`\[...\]`、`$...$`、`\(...\)`）转换为可编辑的 Word 公式。
|
||||||
- :material-file-document-outline: **智能文件名**：可配置标题来源（对话标题、AI 生成或 Markdown 标题）
|
- :material-graph: **Mermaid 图表**：Mermaid 流程图和时序图渲染为文档中的图片。
|
||||||
|
- :material-book-open-page-variant: **引用与参考**：自动从 OpenWebUI 来源生成参考资料章节，支持可点击的引用链接。
|
||||||
|
- :material-brain-off: **移除思考过程**：自动移除 AI 思考块（`<think>`、`<analysis>`）。
|
||||||
|
- :material-table: **增强表格**：智能列宽、列对齐（`:---`、`---:`、`:---:`）、表头跨页重复。
|
||||||
|
- :material-format-quote-close: **引用块支持**：Markdown 引用块渲染为带左侧边框的灰色斜体样式。
|
||||||
|
- :material-translate: **多语言支持**：正确处理中文和英文文本，无乱码问题。
|
||||||
|
- :material-file-document-outline: **智能文件名**：可配置标题来源（对话标题、AI 生成或 Markdown 标题）。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -26,8 +32,13 @@ Export to Word 插件会把聊天消息从 Markdown 转成精致的 Word 文档
|
|||||||
您可以通过插件设置中的 **Valves** 按钮配置以下选项：
|
您可以通过插件设置中的 **Valves** 按钮配置以下选项：
|
||||||
|
|
||||||
| Valve | 说明 | 默认值 |
|
| Valve | 说明 | 默认值 |
|
||||||
| :------------- | :--------------------------------------------------------------------------------------------------------------- | :----------- |
|
| :--- | :--- | :--- |
|
||||||
| `TITLE_SOURCE` | 文档标题/文件名的来源。选项：`chat_title` (对话标题), `ai_generated` (AI 生成), `markdown_title` (Markdown 标题) | `chat_title` |
|
| `TITLE_SOURCE` | 文档标题/文件名的来源。选项：`chat_title` (对话标题), `ai_generated` (AI 生成), `markdown_title` (Markdown 标题) | `chat_title` |
|
||||||
|
| `MERMAID_JS_URL` | Mermaid.js 库的 URL（用于图表渲染）。 | `https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js` |
|
||||||
|
| `MERMAID_PNG_SCALE` | Mermaid PNG 生成缩放比例（分辨率）。越高越清晰但文件越大。 | `3.0` |
|
||||||
|
| `MERMAID_DISPLAY_SCALE` | Mermaid 在 Word 中的显示比例（视觉大小）。>1.0 放大, <1.0 缩小。 | `1.5` |
|
||||||
|
| `MERMAID_OPTIMIZE_LAYOUT` | 优化 Mermaid 布局: 自动将 LR (左右) 转换为 TD (上下) 以适应页面。 | `True` |
|
||||||
|
| `MERMAID_CAPTIONS_ENABLE` | 启用/禁用 Mermaid 图表的图注。 | `True` |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -47,10 +58,10 @@ Export to Word 插件会把聊天消息从 Markdown 转成精致的 Word 文档
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 支持的 Markdown
|
## 支持的 Markdown 语法
|
||||||
|
|
||||||
| 语法 | Word 效果 |
|
| 语法 | Word 效果 |
|
||||||
| :-------------------------- | :------------------ |
|
| :--- | :--- |
|
||||||
| `# 标题1` 到 `###### 标题6` | 标题级别 1-6 |
|
| `# 标题1` 到 `###### 标题6` | 标题级别 1-6 |
|
||||||
| `**粗体**` / `__粗体__` | 粗体文本 |
|
| `**粗体**` / `__粗体__` | 粗体文本 |
|
||||||
| `*斜体*` / `_斜体_` | 斜体文本 |
|
| `*斜体*` / `_斜体_` | 斜体文本 |
|
||||||
@@ -62,8 +73,12 @@ Export to Word 插件会把聊天消息从 Markdown 转成精致的 Word 文档
|
|||||||
| `~~删除线~~` | 删除线 |
|
| `~~删除线~~` | 删除线 |
|
||||||
| `- 项目` / `* 项目` | 无序列表 |
|
| `- 项目` / `* 项目` | 无序列表 |
|
||||||
| `1. 项目` | 有序列表 |
|
| `1. 项目` | 有序列表 |
|
||||||
| Markdown 表格 | 带边框表格 |
|
| Markdown 表格 | **增强表格**（智能列宽） |
|
||||||
| `---` / `***` | 水平分割线 |
|
| `---` / `***` | 水平分割线 |
|
||||||
|
| `$$LaTeX$$` 或 `\[LaTeX\]` | **原生 Word 公式**（块级） |
|
||||||
|
| `$LaTeX$` 或 `\(LaTeX\)` | **原生 Word 公式**（行内） |
|
||||||
|
| ` ```mermaid ... ``` ` | **Mermaid 图表**（图片形式） |
|
||||||
|
| `[1]` 引用标记 | **可点击链接**到参考资料 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -71,7 +86,9 @@ Export to Word 插件会把聊天消息从 Markdown 转成精致的 Word 文档
|
|||||||
|
|
||||||
!!! note "前置条件"
|
!!! note "前置条件"
|
||||||
- `python-docx==1.1.2`（文档生成）
|
- `python-docx==1.1.2`（文档生成）
|
||||||
- `Pygments>=2.15.0`（语法高亮，建议安装）
|
- `Pygments>=2.15.0`（语法高亮）
|
||||||
|
- `latex2mathml`（LaTeX 转 MathML）
|
||||||
|
- `mathml2omml`（MathML 转 Office Math）
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -61,9 +61,9 @@ Actions are interactive plugins that:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
Export the current conversation to a formatted Word doc with syntax highlighting, AI-generated titles, and perfect Markdown rendering (tables, quotes, lists).
|
Export the current conversation to a formatted Word doc with **syntax highlighting**, **native math equations**, **Mermaid diagrams**, **citations**, and **enhanced table formatting**.
|
||||||
|
|
||||||
**Version:** 0.1.1
|
**Version:** 0.2.0
|
||||||
|
|
||||||
[:octicons-arrow-right-24: Documentation](export-to-word.md)
|
[:octicons-arrow-right-24: Documentation](export-to-word.md)
|
||||||
|
|
||||||
|
|||||||
@@ -61,9 +61,9 @@ Actions 是交互式插件，能够：
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
将当前对话导出为完美格式的 Word 文档，支持代码语法高亮、AI 智能标题生成以及表格、引用等 Markdown 元素的精准渲染。
|
将当前对话导出为完美格式的 Word 文档，支持**代码语法高亮**、**原生数学公式**、**Mermaid 图表**、**引用资料**以及**增强表格**渲染。
|
||||||
|
|
||||||
**版本：** 0.1.1
|
**版本：** 0.2.0
|
||||||
|
|
||||||
[:octicons-arrow-right-24: 查看文档](export-to-word.md)
|
[:octicons-arrow-right-24: 查看文档](export-to-word.md)
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user