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

Add PowerPoint to Markdown conversion

hugohe3eb6ce976ee6a
diff --git a/AGENTS.md b/AGENTS.md
index 3d840a88..ccd29b4b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,6 +29,7 @@ PPT Master is an AI-driven presentation generation system. Through multi-role co
# 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/ppt_to_md.py <PPTX_file>
python3 skills/ppt-master/scripts/web_to_md.py <URL>
node skills/ppt-master/scripts/web_to_md.cjs <URL>
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 3ac97ff2..65e794b1 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -46,6 +46,7 @@ description: >
|--------|---------|
| `${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/ppt_to_md.py` | PowerPoint to Markdown |
| `${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 |
@@ -86,6 +87,7 @@ When the user provides non-Markdown content, convert immediately:
|---------------|---------|
| PDF file | `python3 ${SKILL_DIR}/scripts/pdf_to_md.py <file>` |
| DOCX / Word / Office document | `python3 ${SKILL_DIR}/scripts/doc_to_md.py <file>` |
+| PPTX / PowerPoint deck | `python3 ${SKILL_DIR}/scripts/ppt_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>` |
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 07f8f533..6fd574c2 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -17,6 +17,8 @@ Typical end-to-end workflow:
```bash
python3 scripts/pdf_to_md.py <file.pdf>
+# or
+python3 scripts/ppt_to_md.py <deck.pptx>
python3 scripts/project_manager.py init <project_name> --format ppt169
python3 scripts/project_manager.py import-sources <project_path> <source_files...> --move
python3 scripts/total_md_split.py <project_path>
@@ -34,7 +36,7 @@ python3 scripts/update_repo.py
| Area | Primary scripts | Documentation |
|------|-----------------|---------------|
-| Conversion | `pdf_to_md.py`, `doc_to_md.py`, `web_to_md.py`, `web_to_md.cjs` | [docs/conversion.md](./docs/conversion.md) |
+| Conversion | `pdf_to_md.py`, `doc_to_md.py`, `ppt_to_md.py`, `web_to_md.py`, `web_to_md.cjs` | [docs/conversion.md](./docs/conversion.md) |
| Project management | `project_manager.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py` | [docs/project.md](./docs/project.md) |
| SVG pipeline | `finalize_svg.py`, `svg_to_pptx.py`, `total_md_split.py`, `svg_quality_checker.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md) |
| Image tools | `image_gen.py`, `analyze_images.py`, `gemini_watermark_remover.py` | [docs/image.md](./docs/image.md) |
@@ -43,6 +45,15 @@ python3 scripts/update_repo.py
## High-Frequency Commands
+Conversion:
+
+```bash
+python3 scripts/pdf_to_md.py <file.pdf>
+python3 scripts/ppt_to_md.py <deck.pptx>
+python3 scripts/doc_to_md.py <file.docx>
+python3 scripts/web_to_md.py <url>
+```
+
Project setup:
```bash
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index a9ae4f83..4a7cb610 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -1,6 +1,6 @@
# Conversion Tools
-Source conversion tools turn PDFs, documents, and web pages into Markdown before project creation.
+Source conversion tools turn PDFs, documents, slide decks, and web pages into Markdown before project creation.
## `pdf_to_md.py`
@@ -54,6 +54,37 @@ brew install pandoc
sudo apt install pandoc
```
+## `ppt_to_md.py`
+
+Structured PowerPoint-to-Markdown converter for Open XML slide decks.
+
+Supported formats include:
+- `.pptx`, `.pptm`
+- `.ppsx`, `.ppsm`
+- `.potx`, `.potm`
+
+```bash
+python3 scripts/ppt_to_md.py sales_deck.pptx
+python3 scripts/ppt_to_md.py sales_deck.pptx -o output.md
+python3 scripts/ppt_to_md.py ./decks
+python3 scripts/ppt_to_md.py ./decks -o ./markdown
+python3 scripts/ppt_to_md.py template.ppsx -o notes/template.md
+```
+
+Behavior:
+- extracts slide text in reading order
+- converts PowerPoint tables to Markdown tables
+- exports embedded pictures to a sibling `_files/` directory
+- appends speaker notes when present
+
+Dependency:
+
+```bash
+pip install python-pptx
+```
+
+Legacy `.ppt` is not parsed directly. Resave it as `.pptx` or export it to PDF first.
+
## `web_to_md.py` / `web_to_md.cjs`
Convert web pages to Markdown and download images locally.
diff --git a/skills/ppt-master/scripts/ppt_to_md.py b/skills/ppt-master/scripts/ppt_to_md.py
new file mode 100644
index 00000000..6a8cddd2
--- /dev/null
+++ b/skills/ppt-master/scripts/ppt_to_md.py
@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""
+PowerPoint to Markdown Converter
+
+Extracts slide text, tables, speaker notes, and embedded pictures from
+Open XML PowerPoint files into Markdown.
+
+Primary use case: PPTX source decks -> Markdown for PPT generation input.
+
+Dependency:
+ pip install python-pptx
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from pptx import Presentation
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+
+SUPPORTED_FORMATS = {
+ ".pptx": "PowerPoint Presentation",
+ ".pptm": "Macro-enabled PowerPoint Presentation",
+ ".ppsx": "PowerPoint Slide Show",
+ ".ppsm": "Macro-enabled PowerPoint Slide Show",
+ ".potx": "PowerPoint Template",
+ ".potm": "Macro-enabled PowerPoint Template",
+}
+
+
+@dataclass
+class LeafShape:
+ """Flattened leaf shape with stable position ordering."""
+
+ shape: object
+ top: int
+ left: int
+
+
+def normalize_text(value: str) -> str:
+ """Collapse whitespace while preserving paragraph boundaries elsewhere."""
+ value = value.replace("\r\n", "\n").replace("\r", "\n")
+ lines = [re.sub(r"\s+", " ", line).strip() for line in value.split("\n")]
+ lines = [line for line in lines if line]
+ return "\n".join(lines)
+
+
+def escape_table_cell(value: str) -> str:
+ """Escape Markdown table syntax inside a cell."""
+ return normalize_text(value).replace("|", r"\|") or " "
+
+
+def iter_leaf_shapes(shapes: object) -> list[LeafShape]:
+ """Return a flattened, reading-order list of shapes."""
+ items: list[LeafShape] = []
+ for shape in shapes:
+ if shape.shape_type == MSO_SHAPE_TYPE.GROUP:
+ items.extend(iter_leaf_shapes(shape.shapes))
+ continue
+ items.append(
+ LeafShape(
+ shape=shape,
+ top=int(getattr(shape, "top", 0) or 0),
+ left=int(getattr(shape, "left", 0) or 0),
+ )
+ )
+ items.sort(key=lambda item: (item.top, item.left))
+ return items
+
+
+def text_frame_to_markdown(text_frame: object) -> str:
+ """Convert a PowerPoint text frame into Markdown."""
+ paragraphs = []
+ visible_paragraphs = [
+ paragraph for paragraph in text_frame.paragraphs
+ if normalize_text(paragraph.text)
+ ]
+ if not visible_paragraphs:
+ return ""
+
+ list_like = any(paragraph.level > 0 for paragraph in visible_paragraphs)
+ if not list_like:
+ list_like = len(visible_paragraphs) > 1
+
+ for paragraph in visible_paragraphs:
+ text = normalize_text(paragraph.text)
+ if not text:
+ continue
+ if list_like:
+ indent = " " * max(paragraph.level, 0)
+ paragraphs.append(f"{indent}- {text}")
+ else:
+ paragraphs.append(text)
+
+ if list_like:
+ return "\n".join(paragraphs)
+ return "\n\n".join(paragraphs)
+
+
+def table_to_markdown(table: object) -> str:
+ """Convert a PowerPoint table to a Markdown table."""
+ rows = []
+ for row in table.rows:
+ cells = [escape_table_cell(cell.text) for cell in row.cells]
+ rows.append(cells)
+
+ if not rows:
+ return ""
+
+ column_count = max(len(row) for row in rows)
+ normalized_rows = [row + [" "] * (column_count - len(row)) for row in rows]
+ header = normalized_rows[0]
+ separator = ["---"] * column_count
+ body = normalized_rows[1:]
+
+ lines = [
+ "| " + " | ".join(header) + " |",
+ "| " + " | ".join(separator) + " |",
+ ]
+ for row in body:
+ lines.append("| " + " | ".join(row) + " |")
+ return "\n".join(lines)
+
+
+def save_picture(shape: object, asset_dir: Path, slide_index: int, image_index: int) -> str | None:
+ """Persist a picture shape to the output asset directory."""
+ try:
+ image = shape.image
+ except Exception:
+ return None
+
+ ext = (image.ext or "png").lower()
+ filename = f"slide_{slide_index:02d}_image_{image_index:02d}.{ext}"
+ output_path = asset_dir / filename
+ output_path.write_bytes(image.blob)
+ return filename
+
+
+def extract_notes(slide: object) -> str:
+ """Extract speaker notes text from a slide, if available."""
+ try:
+ notes_slide = slide.notes_slide
+ except Exception:
+ return ""
+
+ blocks = []
+ for item in iter_leaf_shapes(notes_slide.shapes):
+ shape = item.shape
+ if not getattr(shape, "has_text_frame", False):
+ continue
+ text = text_frame_to_markdown(shape.text_frame)
+ if text:
+ blocks.append(text)
+
+ return "\n\n".join(blocks).strip()
+
+
+def convert_presentation_to_markdown(
+ input_path: str,
+ output_path: str | None = None,
+) -> str:
+ """Convert a supported PowerPoint file to Markdown."""
+ 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}")
+ print(" Legacy .ppt files should be resaved as .pptx or exported to PDF first.")
+ return ""
+
+ print(f"[INFO] Converting {SUPPORTED_FORMATS[suffix]}: {input_file.name}")
+
+ if output_path:
+ out_file = Path(output_path)
+ else:
+ out_file = input_file.with_suffix(".md")
+
+ out_file.parent.mkdir(parents=True, exist_ok=True)
+ asset_dir = out_file.parent / f"{out_file.stem}_files"
+
+ presentation = Presentation(str(input_file))
+ lines = [
+ f"# {input_file.stem}",
+ "",
+ f"- Source: `{input_file.name}`",
+ f"- Total slides: {len(presentation.slides)}",
+ "",
+ ]
+
+ image_count = 0
+ asset_dir_used = False
+
+ for slide_index, slide in enumerate(presentation.slides, 1):
+ lines.append(f"## Slide {slide_index}")
+ lines.append("")
+
+ blocks = []
+ for item in iter_leaf_shapes(slide.shapes):
+ shape = item.shape
+
+ if getattr(shape, "has_table", False):
+ table_md = table_to_markdown(shape.table)
+ if table_md:
+ blocks.append(table_md)
+ continue
+
+ if shape.shape_type == MSO_SHAPE_TYPE.PICTURE:
+ next_image_index = image_count + 1
+ asset_dir.mkdir(parents=True, exist_ok=True)
+ filename = save_picture(shape, asset_dir, slide_index, next_image_index)
+ if filename is None:
+ blocks.append(f"> [Image] {getattr(shape, 'name', 'Picture')}")
+ continue
+
+ image_count = next_image_index
+ asset_dir_used = True
+ blocks.append(f"![Slide {slide_index} Image {image_count}]({asset_dir.name}/{filename})")
+ continue
+
+ if getattr(shape, "has_text_frame", False):
+ text_md = text_frame_to_markdown(shape.text_frame)
+ if text_md:
+ blocks.append(text_md)
+ continue
+
+ if getattr(shape, "has_chart", False):
+ blocks.append(f"> [Chart] {getattr(shape, 'name', 'Chart')}")
+
+ if blocks:
+ lines.append("\n\n".join(blocks))
+ lines.append("")
+ else:
+ lines.append("_No extractable text content._")
+ lines.append("")
+
+ notes_md = extract_notes(slide)
+ if notes_md:
+ lines.append("### Speaker Notes")
+ lines.append("")
+ lines.append(notes_md)
+ lines.append("")
+
+ markdown_content = "\n".join(lines).strip() + "\n"
+ out_file.write_text(markdown_content, encoding="utf-8")
+
+ print(f"[OK] Saved Markdown to: {out_file}")
+ if asset_dir_used:
+ media_files = [path for path in asset_dir.iterdir() if path.is_file()]
+ print(f" Extracted {len(media_files)} image file(s) -> {asset_dir}")
+
+ return markdown_content
+
+
+def process_directory(input_dir: str, output_dir: str | None = None) -> None:
+ """Convert all supported PowerPoint files in a directory to Markdown."""
+ input_path = Path(input_dir)
+
+ if output_dir:
+ output_path = Path(output_dir)
+ else:
+ output_path = input_path
+
+ presentation_files = sorted(
+ path for path in input_path.iterdir()
+ if path.is_file() and path.suffix.lower() in SUPPORTED_FORMATS
+ )
+
+ print(f"Found {len(presentation_files)} PowerPoint files")
+
+ for presentation_file in presentation_files:
+ output_file = output_path / f"{presentation_file.stem}.md"
+ print(f"Processing: {presentation_file.name}")
+ result = convert_presentation_to_markdown(str(presentation_file), str(output_file))
+ if not result:
+ print(f"[WARN] Skipped failed file: {presentation_file.name}")
+
+
+def main() -> None:
+ """Run the CLI entry point."""
+ parser = argparse.ArgumentParser(
+ description="Convert PowerPoint files to Markdown",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+Examples:
+ python ppt_to_md.py slides.pptx
+ python ppt_to_md.py slides.pptx -o output.md
+ python ppt_to_md.py ./decks
+ python ppt_to_md.py ./decks -o ./markdown
+ python ppt_to_md.py deck.ppsx -o notes/deck.md
+
+Supported formats:
+ .pptx .pptm .ppsx .ppsm .potx .potm
+
+Legacy .ppt is not parsed directly. Resave it as .pptx or export it to PDF first.
+ """,
+ )
+ parser.add_argument("input", help="Input PowerPoint file or directory")
+ parser.add_argument("-o", "--output", help="Output Markdown file or directory path")
+
+ args = parser.parse_args()
+ input_path = Path(args.input)
+
+ if input_path.is_file():
+ output = args.output or str(input_path.with_suffix(".md"))
+ result = convert_presentation_to_markdown(str(input_path), output)
+ sys.exit(0 if result else 1)
+ if input_path.is_dir():
+ process_directory(str(input_path), args.output)
+ sys.exit(0)
+
+ print(f"Error: File or directory not found: {args.input}")
+ sys.exit(1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.py
index 0d84a931..aea7fc94 100644
--- a/skills/ppt-master/scripts/project_manager.py
+++ b/skills/ppt-master/scripts/project_manager.py
@@ -44,6 +44,7 @@ REPO_ROOT = SKILL_DIR.parent.parent
SOURCE_DIRNAME = "sources"
TEXT_SOURCE_SUFFIXES = {".md", ".markdown", ".txt"}
PDF_SUFFIXES = {".pdf"}
+PRESENTATION_SUFFIXES = {".pptx", ".pptm", ".ppsx", ".ppsm", ".potx", ".potm"}
DOC_SUFFIXES = {
".docx", ".doc", ".odt", ".rtf", # Office documents
".epub", # eBooks
@@ -240,6 +241,17 @@ class ProjectManager:
]
)
+ def _import_presentation(self, presentation_path: Path, markdown_path: Path) -> None:
+ self._run_tool(
+ [
+ sys.executable,
+ str(TOOLS_DIR / "ppt_to_md.py"),
+ str(presentation_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):
@@ -453,6 +465,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 PRESENTATION_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 presentation 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 presentation auto-conversion because {canonical_markdown_path.name} already exists"
+ )
+ continue
+ markdown_path = canonical_markdown_path
+ try:
+ self._import_presentation(archived_path, markdown_path)
+ summary["markdown"].append(str(markdown_path))
+ except Exception as exc: # pragma: no cover - summary path
+ summary["skipped"].append(f"{item}: presentation 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: