Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

feat: add doc_to_md.py for DOCX and multi-format document conversion via Pandoc

hugohe3b99b2bd7c807
diff --git a/AGENTS.md b/AGENTS.md
index 7cc944c3..b746349b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,7 +4,7 @@ This file serves as the project entry point for general AI agents. Before execut
## Project Overview
-PPT Master is an AI-driven multi-format SVG content generation system. Through multi-role collaboration (Strategist → Image_Generator → Executor → Optimizer), it converts source documents (PDF/URL/Markdown) into high-quality SVG pages and exports them as PPTX.
+PPT Master is an AI-driven multi-format SVG content generation system. Through multi-role collaboration (Strategist → Image_Generator → Executor → Optimizer), it converts source documents (PDF/DOCX/URL/Markdown) into high-quality SVG pages and exports them as PPTX.
**Core Pipeline**: `Source Document → Create Project → Template Option → Strategist Eight Confirmations → [Image_Generator] → Executor → Post-processing → Export PPTX`
@@ -20,6 +20,7 @@ PPT Master is an AI-driven multi-format SVG content generation system. Through m
```bash
# Source content conversion
python3 skills/ppt-master/scripts/pdf_to_md.py <PDF_file>
+python3 skills/ppt-master/scripts/doc_to_md.py <DOCX_or_other_file> # Requires: pandoc (DOCX/EPUB/HTML/LaTeX/RST/etc.)
python3 skills/ppt-master/scripts/web_to_md.py <URL>
node skills/ppt-master/scripts/web_to_md.cjs <URL>
diff --git a/CLAUDE.md b/CLAUDE.md
index 748b0a7a..9102c25b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides a project overview for Claude Code. Before executing PPT gene
## Project Overview
-PPT Master is an AI-driven multi-format SVG content generation system. Through multi-role collaboration (Strategist → Image_Generator → Executor → Optimizer), it converts source documents (PDF/URL/Markdown) into high-quality SVG pages and exports them as PPTX.
+PPT Master is an AI-driven multi-format SVG content generation system. Through multi-role collaboration (Strategist → Image_Generator → Executor → Optimizer), it converts source documents (PDF/DOCX/URL/Markdown) into high-quality SVG pages and exports them as PPTX.
**Core Pipeline**: `Source Document → Create Project → Template Option → Strategist Eight Confirmations → [Image_Generator] → Executor → Post-processing → Export PPTX`
@@ -13,6 +13,7 @@ PPT Master is an AI-driven multi-format SVG content generation system. Through m
```bash
# Source content conversion
python3 skills/ppt-master/scripts/pdf_to_md.py <PDF_file>
+python3 skills/ppt-master/scripts/doc_to_md.py <DOCX_or_other_file> # Requires: pandoc (DOCX/EPUB/HTML/LaTeX/RST/etc.)
python3 skills/ppt-master/scripts/web_to_md.py <URL>
node skills/ppt-master/scripts/web_to_md.cjs <URL>
diff --git a/README.md b/README.md
index fcd99881..21e0e723 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
English | [中文](./README_CN.md)
-Drop in a PDF, URL, or Markdown file — AI generates **beautifully designed presentations that you can edit directly in PowerPoint**. Supports PPT 16:9, social media cards, marketing posters, and 10+ other formats.
+Drop in a PDF, DOCX, URL, or Markdown file — AI generates **beautifully designed presentations that you can edit directly in PowerPoint**. Supports PPT 16:9, social media cards, marketing posters, and 10+ other formats.
> 💡 **Major Update**: The project architecture has undergone a massive upgrade (Skill-based architecture):
> 1. **Lower Token Consumption & Model Dependency**: Significantly reduced token consumption. Now, even non-Opus models can generate decent results.
@@ -40,9 +40,9 @@ Drop in a PDF, URL, or Markdown file — AI generates **beautifully designed pre
## 🏗️ System Architecture
```
-User Input (PDF/URL/Markdown)
+User Input (PDF/DOCX/URL/Markdown)
↓
-[Source Content Conversion] → pdf_to_md.py / web_to_md.py
+[Source Content Conversion] → pdf_to_md.py / doc_to_md.py / web_to_md.py
↓
[Create Project] → project_manager.py init <project_name> --format <format>
↓
@@ -111,6 +111,18 @@ If you need to use the `web_to_md.cjs` tool (for converting web pages from WeCha
> 💡 **Verify Installation**: Run `node --version` to confirm version ≥ 18
+#### Pandoc (Optional)
+
+If you need to use the `doc_to_md.py` tool (for converting DOCX, EPUB, LaTeX, and other document formats to Markdown), install [Pandoc](https://pandoc.org/).
+
+| Platform | Recommended Installation |
+|----------|-------------------------|
+| **macOS** | Use [Homebrew](https://brew.sh/): `brew install pandoc` |
+| **Windows** | Download installer from [Pandoc Official Website](https://pandoc.org/installing.html) |
+| **Linux** | Use package manager: `sudo apt install pandoc` (Ubuntu/Debian) |
+
+> 💡 **Verify Installation**: Run `pandoc --version` to confirm it is installed
+
### 2. Clone Repository and Install Dependencies
```bash
@@ -207,6 +219,9 @@ python3 skills/ppt-master/scripts/project_manager.py import-sources <project_pat
# PDF to Markdown
python3 skills/ppt-master/scripts/pdf_to_md.py <PDF_file>
+# DOCX / Office documents to Markdown (requires pandoc)
+python3 skills/ppt-master/scripts/doc_to_md.py <DOCX_file>
+
# Post-processing (run in order)
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
python3 skills/ppt-master/scripts/finalize_svg.py <project_path>
diff --git a/README_CN.md b/README_CN.md
index 1860507c..49aa92d2 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -6,7 +6,7 @@
[English](./README.md) | 中文
-丢进一份 PDF、网址或 Markdown,AI 自动生成**可在 PowerPoint 中直接编辑**的精美演示文稿。支持 PPT 16:9、小红书、朋友圈等 10+ 种格式。
+丢进一份 PDF、DOCX、网址或 Markdown,AI 自动生成**可在 PowerPoint 中直接编辑**的精美演示文稿。支持 PPT 16:9、小红书、朋友圈等 10+ 种格式。
> 💡 **架构大更新**:目前项目架构已进行重大升级(Skill-based architecture):
> 1. **大幅减少 Token 消耗与模型依赖**:现在即使不使用 Opus 模型,其他模型也能生成质量尚可的结果。
@@ -40,9 +40,9 @@
## 🏗️ 系统架构
```
-用户输入 (PDF/URL/Markdown)
+用户输入 (PDF/DOCX/URL/Markdown)
↓
-[源内容转换] → pdf_to_md.py / web_to_md.py
+[源内容转换] → pdf_to_md.py / doc_to_md.py / web_to_md.py
↓
[创建项目] → project_manager.py init <项目名> --format <格式>
↓
@@ -110,6 +110,18 @@
> 💡 **验证安装**:运行 `node --version` 确认版本 ≥ 18
+#### Pandoc(可选)
+
+如需使用 `doc_to_md.py` 工具(用于将 DOCX、EPUB、LaTeX 等文档格式转换为 Markdown),需安装 [Pandoc](https://pandoc.org/)。
+
+| 平台 | 推荐安装方式 |
+|------|------------|
+| **macOS** | 使用 [Homebrew](https://brew.sh/):`brew install pandoc` |
+| **Windows** | 从 [Pandoc 官网](https://pandoc.org/installing.html) 下载安装包 |
+| **Linux** | 使用系统包管理器:`sudo apt install pandoc`(Ubuntu/Debian) |
+
+> 💡 **验证安装**:运行 `pandoc --version` 确认已安装
+
### 2. 克隆仓库并安装依赖
```bash
@@ -203,6 +215,9 @@ python3 skills/ppt-master/scripts/project_manager.py import-sources <项目路
# PDF 转 Markdown
python3 skills/ppt-master/scripts/pdf_to_md.py <PDF文件>
+# DOCX / Office 文档转 Markdown(需要 pandoc)
+python3 skills/ppt-master/scripts/doc_to_md.py <DOCX文件>
+
# 后处理三步(必须按顺序执行)
python3 skills/ppt-master/scripts/total_md_split.py <项目路径>
python3 skills/ppt-master/scripts/finalize_svg.py <项目路径>
diff --git a/requirements.txt b/requirements.txt
index 576dd48d..9b8f8664 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -30,6 +30,15 @@ reportlab>=4.0.0
# 用于将 PDF 文件转换为 Markdown 格式,支持文本、图片、表格提取
PyMuPDF>=1.23.0
+# ─────────────────────────────────────────────────────────────
+# 文档转 Markdown 工具 (skills/ppt-master/scripts/doc_to_md.py)
+# ─────────────────────────────────────────────────────────────
+# 使用 Pandoc 将 DOCX/EPUB/HTML/LaTeX/RST 等格式转换为 Markdown
+# 无 Python 包依赖,需要系统安装 pandoc:
+# macOS: brew install pandoc
+# Ubuntu: sudo apt install pandoc
+# Windows: https://pandoc.org/installing.html
+
# ─────────────────────────────────────────────────────────────
# 图片处理工具
# ─────────────────────────────────────────────────────────────
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 871e258a..677a1be2 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -2,7 +2,7 @@
name: ppt-master
description: >
AI-driven multi-format SVG content generation system. Converts source documents
- (PDF/URL/Markdown) into high-quality SVG pages and exports to PPTX through
+ (PDF/DOCX/URL/Markdown) into high-quality SVG pages and exports to PPTX through
multi-role collaboration. Use when user asks to "create PPT", "make presentation",
"生成PPT", "做PPT", "制作演示文稿", or mentions "ppt-master".
---
@@ -36,6 +36,7 @@ description: >
| Script | Purpose |
|--------|---------|
| `${SKILL_DIR}/scripts/pdf_to_md.py` | PDF to Markdown |
+| `${SKILL_DIR}/scripts/doc_to_md.py` | Documents to Markdown via Pandoc (DOCX, EPUB, HTML, LaTeX, RST, etc.) |
| `${SKILL_DIR}/scripts/web_to_md.py` | Web page to Markdown |
| `${SKILL_DIR}/scripts/web_to_md.cjs` | WeChat / high-security sites to Markdown |
| `${SKILL_DIR}/scripts/project_manager.py` | Project init / validate / manage |
@@ -68,13 +69,15 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
### Step 1: Source Content Processing
-🚧 **GATE**: User has provided source material (PDF / URL / Markdown file / text description / conversation content — any form is acceptable).
+🚧 **GATE**: User has provided source material (PDF / DOCX / EPUB / URL / Markdown file / text description / conversation content — any form is acceptable).
When the user provides non-Markdown content, convert immediately:
| User Provides | Command |
|---------------|---------|
| PDF file | `python3 ${SKILL_DIR}/scripts/pdf_to_md.py <file>` |
+| DOCX / Word / Office document | `python3 ${SKILL_DIR}/scripts/doc_to_md.py <file>` |
+| EPUB / HTML / LaTeX / RST / other | `python3 ${SKILL_DIR}/scripts/doc_to_md.py <file>` |
| Web link | `python3 ${SKILL_DIR}/scripts/web_to_md.py <URL>` |
| WeChat / high-security site | `node ${SKILL_DIR}/scripts/web_to_md.cjs <URL>` |
| Markdown | Read directly |
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index a6f2febf..c1394b7d 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -8,6 +8,7 @@ This directory contains utility tools for project management, validation, and fi
graph TB
subgraph Input["Input Conversion"]
A1[pdf_to_md.py]
+ A1b[doc_to_md.py]
A2[web_to_md.py / .cjs]
end
@@ -62,7 +63,7 @@ graph TB
### Core Workflow
```
-Source Document → [pdf_to_md / web_to_md] → Markdown
+Source Document → [pdf_to_md / doc_to_md / web_to_md] → Markdown
↓
[project_manager init]
↓
@@ -79,7 +80,7 @@ Source Document → [pdf_to_md / web_to_md] → Markdown
| Category | Tool | Description |
|----------|------|-------------|
-| **Input Conversion** | `pdf_to_md.py`, `web_to_md.py/.cjs` | Convert PDF/web pages to Markdown |
+| **Input Conversion** | `pdf_to_md.py`, `doc_to_md.py`, `web_to_md.py/.cjs` | Convert PDF/DOCX/web pages to Markdown |
| **Project Management** | `project_manager.py` | Create and validate projects |
| **Post-processing** | `finalize_svg.py` ⭐ | Unified entry point, invokes the 6 tools below |
| ↳ Sub-tool | `embed_icons.py` | Embed icon placeholders |
@@ -147,6 +148,37 @@ pip install PyMuPDF
---
+### 0.3. doc_to_md.py — Document to Markdown Tool (Pandoc-based)
+
+Uses Pandoc to convert various document formats to Markdown. Ideal for converting DOCX lecture notes, manuscripts, and other documents.
+
+**Supported formats**: `.docx`, `.doc`, `.odt`, `.rtf`, `.epub`, `.html`, `.tex`, `.rst`, `.org`, `.ipynb`, `.typ`
+
+**Usage**:
+
+```bash
+# Convert a Word document
+python3 scripts/doc_to_md.py lecture.docx
+
+# Specify output file
+python3 scripts/doc_to_md.py lecture.docx -o output.md
+
+# Convert other formats
+python3 scripts/doc_to_md.py notes.epub
+python3 scripts/doc_to_md.py paper.tex -o paper.md
+```
+
+**Dependencies**:
+
+```bash
+# Install pandoc (required)
+# macOS: brew install pandoc
+# Ubuntu: sudo apt install pandoc
+# Windows: https://pandoc.org/installing.html
+```
+
+---
+
### 0.5. web_to_md.py / web_to_md.cjs — Web Page to Markdown Tool
Scrapes web page content and converts it to Markdown format, automatically downloading images locally.
diff --git a/skills/ppt-master/scripts/doc_to_md.py b/skills/ppt-master/scripts/doc_to_md.py
new file mode 100644
index 00000000..c1b6a3f4
--- /dev/null
+++ b/skills/ppt-master/scripts/doc_to_md.py
@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+Document to Markdown Converter (Pandoc-based)
+
+Uses Pandoc to convert various document formats to Markdown.
+Primary use case: DOCX lecture notes / manuscripts → Markdown for PPT generation.
+
+Dependency: pandoc must be installed
+ macOS: brew install pandoc
+ Ubuntu: sudo apt install pandoc
+ Windows: https://pandoc.org/installing.html
+"""
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+# Supported input formats
+SUPPORTED_FORMATS = {
+ # Office documents
+ ".docx": ("docx", "Microsoft Word"),
+ ".doc": ("doc", "Microsoft Word 97-2003"),
+ ".odt": ("odt", "OpenDocument Text"),
+ ".rtf": ("rtf", "Rich Text Format"),
+ # eBooks
+ ".epub": ("epub", "EPUB"),
+ # Web
+ ".html": ("html", "HTML"),
+ ".htm": ("html", "HTML"),
+ # Academic / technical
+ ".tex": ("latex", "LaTeX"),
+ ".latex": ("latex", "LaTeX"),
+ ".rst": ("rst", "reStructuredText"),
+ ".org": ("org", "Emacs Org-mode"),
+ ".ipynb": ("ipynb", "Jupyter Notebook"),
+ ".typ": ("typst", "Typst"),
+}
+
+# Formats that may contain embedded media
+MEDIA_FORMATS = {".docx", ".odt", ".epub", ".html", ".htm"}
+
+
+def check_pandoc() -> bool:
+ """Check if pandoc is installed."""
+ return shutil.which("pandoc") is not None
+
+
+def convert_to_markdown(input_path: str, output_path: str = None) -> str:
+ """
+ Convert a document to Markdown using Pandoc.
+
+ Args:
+ input_path: Path to the input document.
+ output_path: Path to write the output Markdown (default: same dir, .md extension).
+
+ Returns:
+ The generated Markdown content.
+ """
+ input_file = Path(input_path)
+
+ if not input_file.exists():
+ print(f"[ERROR] File not found: {input_path}")
+ return ""
+
+ suffix = input_file.suffix.lower()
+ if suffix not in SUPPORTED_FORMATS:
+ supported = ", ".join(sorted(SUPPORTED_FORMATS.keys()))
+ print(f"[ERROR] Unsupported format: {suffix}")
+ print(f" Supported: {supported}")
+ return ""
+
+ input_format, format_desc = SUPPORTED_FORMATS[suffix]
+ print(f"[INFO] Converting {format_desc} file: {input_file.name}")
+
+ # Determine output path
+ if output_path:
+ out_file = Path(output_path)
+ else:
+ out_file = input_file.with_suffix(".md")
+
+ # Media extraction directory (use name only — pandoc writes relative paths)
+ rel_media_dir = f"{out_file.stem}_files"
+ media_dir = out_file.parent / rel_media_dir
+
+ # Build pandoc command — use resolved absolute paths for input/output,
+ # but a relative directory name for --extract-media so pandoc writes
+ # relative image references in the markdown.
+ cmd = [
+ "pandoc",
+ "-f", input_format,
+ "-t", "gfm",
+ str(input_file.resolve()),
+ "-o", str(out_file.resolve()),
+ "--wrap", "none",
+ "--strip-comments",
+ ]
+
+ # Extract embedded media for formats that support it
+ if suffix in MEDIA_FORMATS:
+ cmd.extend(["--extract-media", rel_media_dir])
+
+ try:
+ result = subprocess.run(cmd, capture_output=True, text=True,
+ cwd=str(out_file.parent))
+ except FileNotFoundError:
+ print("[ERROR] pandoc not found! Please install it first:")
+ print(" macOS: brew install pandoc")
+ print(" Ubuntu: sudo apt install pandoc")
+ print(" Windows: https://pandoc.org/installing.html")
+ return ""
+
+ if result.returncode != 0:
+ print(f"[ERROR] Pandoc conversion failed:\n{result.stderr}")
+ return ""
+
+ # Read generated markdown
+ if not out_file.exists():
+ print("[ERROR] Conversion completed but no output file was generated")
+ return ""
+
+ markdown_content = out_file.read_text(encoding="utf-8")
+
+ # --- Post-processing: fix media paths ---
+
+ # 1. Flatten nested media/ subdirectory that pandoc creates
+ nested_media = media_dir / "media"
+ if nested_media.exists():
+ for f in nested_media.iterdir():
+ if f.is_file():
+ target = media_dir / f.name
+ shutil.move(str(f), str(target))
+ try:
+ nested_media.rmdir()
+ except OSError:
+ pass
+ # Fix references: {dir}/media/img.png → {dir}/img.png
+ markdown_content = markdown_content.replace(
+ f"{rel_media_dir}/media/", f"{rel_media_dir}/"
+ )
+
+ # 2. Convert any absolute paths to relative (safety net)
+ abs_media_str = str(media_dir.resolve()).replace("\\", "/")
+ if abs_media_str in markdown_content:
+ markdown_content = markdown_content.replace(abs_media_str, rel_media_dir)
+ # Also handle backslash variant on Windows
+ abs_media_str_bs = str(media_dir.resolve())
+ if abs_media_str_bs in markdown_content:
+ markdown_content = markdown_content.replace(abs_media_str_bs, rel_media_dir)
+
+ # 3. Convert <img> HTML tags to Markdown ![alt](src) syntax
+ # Pandoc generates <img> when the source has styling (width/height)
+ def _img_to_md(m):
+ src = m.group("src")
+ alt = m.group("alt") or Path(src).stem
+ return f"![{alt}]({src})"
+
+ markdown_content = re.sub(
+ r'<img\s[^>]*?src="(?P<src>[^"]+)"[^>]*?(?:alt="(?P<alt>[^"]*)")?[^>]*/?\s*>',
+ _img_to_md,
+ markdown_content,
+ )
+ # Handle alt before src order as well
+ markdown_content = re.sub(
+ r'<img\s[^>]*?alt="(?P<alt>[^"]*)"[^>]*?src="(?P<src>[^"]+)"[^>]*/?\s*>',
+ _img_to_md,
+ markdown_content,
+ )
+
+ out_file.write_text(markdown_content, encoding="utf-8")
+
+ # Report results
+ size = out_file.stat().st_size
+ print(f"[OK] Saved Markdown to: {out_file} ({_format_size(size)})")
+
+ if media_dir.exists():
+ media_files = [f for f in media_dir.rglob("*") if f.is_file()]
+ if media_files:
+ print(f" Extracted {len(media_files)} media file(s) → {media_dir}")
+
+ return markdown_content
+
+
+def _format_size(size: int) -> str:
+ """Format file size for display."""
+ for unit in ("B", "KB", "MB"):
+ if size < 1024:
+ return f"{size:.0f} {unit}"
+ size /= 1024
+ return f"{size:.1f} GB"
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Convert documents to Markdown using Pandoc",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+Examples:
+ python doc_to_md.py lecture.docx # Convert Word document
+ python doc_to_md.py lecture.docx -o output.md # Specify output path
+ python doc_to_md.py notes.odt # Convert OpenDocument
+
+Supported formats:
+ Office: .docx .doc .odt .rtf
+ eBooks: .epub
+ Web: .html .htm
+ Academic: .tex .rst .org .ipynb .typ
+ """,
+ )
+
+ parser.add_argument("input", help="Input document file")
+ parser.add_argument("-o", "--output", help="Output Markdown file path")
+
+ args = parser.parse_args()
+
+ if not check_pandoc():
+ print("[ERROR] pandoc not found! Please install it first:")
+ print(" macOS: brew install pandoc")
+ print(" Ubuntu: sudo apt install pandoc")
+ print(" Windows: https://pandoc.org/installing.html")
+ sys.exit(1)
+
+ result = convert_to_markdown(args.input, args.output)
+ sys.exit(0 if result else 1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.py
index bba98b17..aaafae67 100644
--- a/skills/ppt-master/scripts/project_manager.py
+++ b/skills/ppt-master/scripts/project_manager.py
@@ -45,6 +45,13 @@ REPO_ROOT = SKILL_DIR.parent.parent
SOURCE_DIRNAME = "sources"
TEXT_SOURCE_SUFFIXES = {".md", ".markdown", ".txt"}
PDF_SUFFIXES = {".pdf"}
+DOC_SUFFIXES = {
+ ".docx", ".doc", ".odt", ".rtf", # Office documents
+ ".epub", # eBooks
+ ".html", ".htm", # Web pages
+ ".tex", ".latex", ".rst", ".org", # Academic / technical
+ ".ipynb", ".typ", # Notebooks / Typst
+}
WECHAT_HOST_KEYWORDS = ("mp.weixin.qq.com", "weixin.qq.com")
@@ -219,6 +226,17 @@ class ProjectManager:
]
)
+ def _import_doc(self, doc_path: Path, markdown_path: Path) -> None:
+ self._run_tool(
+ [
+ sys.executable,
+ str(TOOLS_DIR / "doc_to_md.py"),
+ str(doc_path),
+ "-o",
+ str(markdown_path),
+ ]
+ )
+
def _import_url(self, url: str, markdown_path: Path) -> None:
host = urlparse(url).netloc.lower()
if any(keyword in host for keyword in WECHAT_HOST_KEYWORDS):
@@ -432,6 +450,25 @@ class ProjectManager:
summary["markdown"].append(str(markdown_path))
except Exception as exc: # pragma: no cover - summary path
summary["skipped"].append(f"{item}: PDF conversion failed ({exc})")
+ elif suffix in DOC_SUFFIXES:
+ canonical_markdown_path = sources_dir / f"{archived_path.stem}.md"
+ if archived_path.stem in explicit_markdown_stems:
+ summary["notes"].append(
+ f"{item}: skipped document auto-conversion because a same-stem Markdown source was provided"
+ )
+ continue
+ if canonical_markdown_path.exists():
+ summary["markdown"].append(str(canonical_markdown_path))
+ summary["notes"].append(
+ f"{item}: skipped document auto-conversion because {canonical_markdown_path.name} already exists"
+ )
+ continue
+ markdown_path = canonical_markdown_path
+ try:
+ self._import_doc(archived_path, markdown_path)
+ summary["markdown"].append(str(markdown_path))
+ except Exception as exc: # pragma: no cover - summary path
+ summary["skipped"].append(f"{item}: document conversion failed ({exc})")
elif suffix == ".txt":
markdown_path = self._normalize_text_source(archived_path, sources_dir)
summary["markdown"].append(str(markdown_path))