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
fix: DOCX charts and table footnotes survive conversion; source_to_md --json keeps stdout to JSON
hugohe322da436d3b87
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.mdindex 90ff5ada..0f402c81 100644--- a/skills/ppt-master/scripts/docs/conversion.md+++ b/skills/ppt-master/scripts/docs/conversion.md@@ -121,7 +121,7 @@ PyMuPDF is licensed under AGPL-3.0, with a commercial license available from ArtHybrid converter: pure-Python for the common formats, pandoc fallback for the rest.Native path (no external binary required):-- `.docx` — via `mammoth`; text-only tables are preserved as pipe Markdown, and OMML / Office Math equations (Word-native or MathType "Convert to Office Math") are rewritten to inline LaTeX. Classic MathType OLE objects carry no OMML and are kept only as their preview image.+- `.docx` — via `mammoth`; text-only tables (with footnotes) and chart data become pipe Markdown, and OMML / Office Math equations (Word-native or MathType "Convert to Office Math") are rewritten to inline LaTeX. Classic MathType OLE objects carry no OMML and are kept only as their preview image.- `.html` / `.htm` — via `markdownify` + `beautifulsoup4`- `.epub` — via `ebooklib` + `markdownify`- `.ipynb` — via `nbconvert`diff --git a/skills/ppt-master/scripts/docs/native-data.md b/skills/ppt-master/scripts/docs/native-data.mdindex 6932bbde..de304652 100644--- a/skills/ppt-master/scripts/docs/native-data.md+++ b/skills/ppt-master/scripts/docs/native-data.md@@ -14,7 +14,7 @@ file no longer repeats. Section titles mirror the owning section of## §2 Metadata placement and bounds-one child `<metadata type="application/json">` (attribute `data-pptx-json` is read-compatible, not canonical); the marker's `data-pptx-replace-with` selects the schema. Provide `x`, `y`, `width`, `height` in metadata or as `data-pptx-x/y/width/height` on the group; omitted bounds are inferred from the fallback geometry (then marker/ancestor `translate` / `scale` apply), complete explicit bounds are absolute slide coordinates. `x` / `y` are finite and inside the 32-bit DrawingML range; `width` / `height` additionally resolve to at least one EMU (tables: per resolved row and column). JSON-first markers require all four bounds in metadata. Classic charts accept root `plot_area` (`x`, `y`, `width`, `height`, a positive rectangle inside the frame → `c:manualLayout`; the frame grows past the plot on the side that carries tick labels until that strip is two axis-font ems tall, because PowerPoint drops the manual vertical layout when its labels do not fit and auto-fits the plot to the frame top instead); ChartEx rejects it. `svg_quality_checker.py` validates marker kind, JSON, bounds/fallback, table rows/columns, chart type and data shape, the authority contract, and (SVG-first) baseline freshness.+one child `<metadata type="application/json">` (attribute `data-pptx-json` is read-compatible, not canonical; the JSON is XML text, so `&` and `<` inside strings are written `&` and `<`); the marker's `data-pptx-replace-with` selects the schema. Provide `x`, `y`, `width`, `height` in metadata or as `data-pptx-x/y/width/height` on the group; omitted bounds are inferred from the fallback geometry (then marker/ancestor `translate` / `scale` apply), complete explicit bounds are absolute slide coordinates. `x` / `y` are finite and inside the 32-bit DrawingML range; `width` / `height` additionally resolve to at least one EMU (tables: per resolved row and column). JSON-first markers require all four bounds in metadata. Classic charts accept root `plot_area` (`x`, `y`, `width`, `height`, a positive rectangle inside the frame → `c:manualLayout`; the frame grows past the plot on the side that carries tick labels until that strip is two axis-font ems tall, because PowerPoint drops the manual vertical layout when its labels do not fit and auto-fits the plot to the frame top instead); ChartEx rejects it. `svg_quality_checker.py` validates marker kind, JSON, bounds/fallback, table rows/columns, chart type and data shape, the authority contract, and (SVG-first) baseline freshness.## §2 Table schema — `ppt-master.semantic-table.v2`diff --git a/skills/ppt-master/scripts/project_management/cli.py b/skills/ppt-master/scripts/project_management/cli.pyindex be7e285d..6103e697 100644--- a/skills/ppt-master/scripts/project_management/cli.py+++ b/skills/ppt-master/scripts/project_management/cli.py@@ -27,6 +27,7 @@ import argparseimport filecmpimport jsonimport os+import statimport reimport shutilimport subprocess@@ -182,6 +183,12 @@ def _read_existing_image_manifest(path: Path) -> list[dict]:def _write_json_atomic(path: Path, payload: object) -> None:"""Write JSON through a same-directory temporary file and atomic rename."""+ try:+ mode = stat.S_IMODE(path.stat().st_mode)+ except FileNotFoundError:+ umask = os.umask(0)+ os.umask(umask)+ mode = 0o666 & ~umaskfd, temp_name = tempfile.mkstemp(prefix=f"{path.stem}.",suffix=".tmp",@@ -191,6 +198,8 @@ def _write_json_atomic(path: Path, payload: object) -> None:with os.fdopen(fd, "w", encoding="utf-8") as handle:json.dump(payload, handle, ensure_ascii=False, indent=2)handle.write("\n")+ # mkstemp creates 0600; keep the file's own (or the default) mode.+ os.chmod(temp_name, mode)os.replace(temp_name, path)except Exception:try:diff --git a/skills/ppt-master/scripts/source_to_md.py b/skills/ppt-master/scripts/source_to_md.pyindex a4f96033..e8012746 100644--- a/skills/ppt-master/scripts/source_to_md.py+++ b/skills/ppt-master/scripts/source_to_md.py@@ -193,10 +193,11 @@ def write_passthrough(warnings=warnings,)for warning in warnings:- print(f"[INFO] {warning}")+ _print_status(f"[INFO] {warning}")_print_status(f"[OK] Saved Markdown to: {output}")_print_status(f" Wrote conversion profile -> {profile}")- print_output(output)+ if not json_output:+ print_output(output)if json_output:payload = build_result_payload(input_path=input_arg,@@ -334,7 +335,8 @@ def dispatch_single(emit_result.unlink(missing_ok=True)if output_path and output_path.is_file():profile = ensure_profile(input_arg, output_path, route.script_name, "web")- print_output(output_path)+ if not args.json:+ print_output(output_path)if args.json:print_json_result(input_arg, output_path, route.script_name, "web", profile)return 0@@ -377,7 +379,8 @@ def dispatch_single(return 1profile = ensure_profile(input_arg, output, route.script_name, conversion_type)- print_output(output)+ if not args.json:+ print_output(output)if args.json:print_json_result(input_arg, output, route.script_name, conversion_type, profile)return 0diff --git a/skills/ppt-master/scripts/source_to_md/doc_to_md.py b/skills/ppt-master/scripts/source_to_md/doc_to_md.pyindex 331f187f..0d65e4e2 100644--- a/skills/ppt-master/scripts/source_to_md/doc_to_md.py+++ b/skills/ppt-master/scripts/source_to_md/doc_to_md.py@@ -3,7 +3,8 @@Document to Markdown Converter (hybrid Python + Pandoc fallback)Primary formats (pure Python, no external tools required):- .docx → mammoth (tables preserved; OMML equations rewritten to inline LaTeX)+ .docx → mammoth (tables and embedded chart data as Markdown tables;+ OMML equations rewritten to inline LaTeX).html → markdownify + BeautifulSoup.epub → ebooklib + markdownify.ipynb → nbconvert@@ -82,6 +83,13 @@ DOCX_NS = {"m": "http://schemas.openxmlformats.org/officeDocument/2006/math",}EMU_PER_INCH = 914400+CHART_NS = "http://schemas.openxmlformats.org/drawingml/2006/chart"+# Word's built-in Title / Subtitle styles carry the cover heading; mammoth+# leaves them as plain paragraphs unless mapped.+DOCX_STYLE_MAP = """+p[style-name='Title'] => h1:fresh+p[style-name='Subtitle'] => h2:fresh+"""MATH_NS = DOCX_NS["m"]W_NS = DOCX_NS["w"]XML_SPACE_ATTR = "{http://www.w3.org/XML/1998/namespace}space"@@ -704,9 +712,27 @@ def _docx_paragraph_text(paragraph: ET.Element) -> str:parts.append("\t")elif local in {"br", "cr"}:parts.append(" ")+ elif local == "footnoteReference":+ parts.append(f"[^{elem.get(f'{{{W_NS}}}id')}]")return "".join(parts).strip()+def _docx_footnote_texts(docx: zipfile.ZipFile) -> dict[str, str]:+ """Return footnote id → plain text from ``word/footnotes.xml``."""+ try:+ root = ET.fromstring(docx.read("word/footnotes.xml"))+ except (KeyError, ET.ParseError):+ return {}+ return {+ note.get(f"{{{W_NS}}}id", ""): " ".join(+ _docx_paragraph_text(paragraph)+ for paragraph in note.findall("w:p", DOCX_NS)+ ).strip()+ for note in root.findall("w:footnote", DOCX_NS)+ if note.get(f"{{{W_NS}}}type") is None+ }++def _docx_table_has_media(table: ET.Element) -> bool:"""Return whether a table contains image-bearing nodes."""return any(_local_name(elem) in {"drawing", "imagedata"} for elem in table.iter())@@ -760,6 +786,7 @@ def _docx_inject_tables_markdown(try:with zipfile.ZipFile(input_file) as docx:document_xml = docx.read("word/document.xml")+ footnotes = _docx_footnote_texts(docx)except (KeyError, zipfile.BadZipFile, OSError):return Nonetry:@@ -776,6 +803,12 @@ def _docx_inject_tables_markdown(markdown = _docx_table_to_markdown(table)if not markdown:continue+ # The table never reaches mammoth, so its footnotes would lose both+ # the reference and the note text; keep them under the table.+ for reference in table.iter(f"{{{W_NS}}}footnoteReference"):+ note_id = reference.get(f"{{{W_NS}}}id", "")+ if footnotes.get(note_id):+ markdown += f"\n\n[^{note_id}]: {footnotes[note_id]}"parent = parent_map.get(table)if parent is None:continue@@ -803,6 +836,93 @@ def _docx_inject_tables_markdown(return out_path, replacements+def _docx_chart_markdown(chart_xml: bytes, name: str) -> str:+ """Render one embedded Word chart's cached data as a Markdown table."""+ import importlib.util++ if importlib.util.find_spec("pptx") is None:+ return f"> [Chart] {name} — data unavailable (python-pptx is not installed)"+ from pptx.chart.chart import Chart+ from pptx.oxml import parse_xml+ from ppt_to_md import chart_to_markdown++ return chart_to_markdown(Chart(parse_xml(chart_xml), None), name)+++def _docx_inject_charts_markdown(+ input_file: Path,+) -> tuple[Path, dict[str, str], list[str]] | None:+ """Place each embedded chart's cached data after its paragraph in a temp DOCX.++ Mammoth drops ``c:chart`` drawings entirely, so the chart values — often+ the only copy of a report's numbers — would vanish from the Markdown.+ """+ try:+ with zipfile.ZipFile(input_file) as docx:+ document_xml = docx.read("word/document.xml")+ rels_root = ET.fromstring(docx.read("word/_rels/document.xml.rels"))+ chart_parts = {+ name: docx.read(name)+ for name in docx.namelist()+ if name.startswith("word/charts/") and name.endswith(".xml")+ }+ except (KeyError, ET.ParseError, zipfile.BadZipFile, OSError):+ return None+ try:+ root = ET.fromstring(document_xml)+ except ET.ParseError:+ return None+ charts = list(root.iter(f"{{{CHART_NS}}}chart"))+ if not charts:+ return None++ rels = {+ rel.attrib.get("Id"): rel.attrib.get("Target", "")+ for rel in rels_root.findall("rel:Relationship", DOCX_NS)+ }+ parent_map = {child: parent for parent in root.iter() for child in parent}+ token_base = uuid.uuid4().hex+ replacements: dict[str, str] = {}+ warnings: list[str] = []+ seen: set[str] = set()+ for chart in charts:+ rel_id = chart.get(f"{{{DOCX_NS['r']}}}id")+ paragraph = parent_map.get(chart)+ while paragraph is not None and _local_name(paragraph) != "p":+ paragraph = parent_map.get(paragraph)+ if not rel_id or rel_id in seen or paragraph is None:+ continue+ seen.add(rel_id)+ name = f"Chart {len(replacements) + 1}"+ part_name = posixpath.normpath(posixpath.join("word", rels.get(rel_id, "")))+ try:+ markdown = _docx_chart_markdown(chart_parts[part_name], name)+ except Exception as exc: # a malformed cache must not sink the document+ markdown = f"> [Chart] {name} — data unavailable ({exc.__class__.__name__})"+ if "data unavailable" in markdown:+ warnings.append(f"{name} ({part_name}): chart data unavailable")+ parent = parent_map[paragraph]+ token = f"MARKDOWNCHART{token_base}{len(replacements):04d}"+ parent.insert(list(parent).index(paragraph) + 1, _make_text_paragraph(token))+ replacements[token] = markdown+ if not replacements:+ return None++ for prefix, uri in DOCX_NS.items():+ if prefix != "rel":+ ET.register_namespace(prefix, uri)+ patched_xml = ET.tostring(root, encoding="utf-8", xml_declaration=True)+ tmp = tempfile.NamedTemporaryFile(suffix=".docx", delete=False)+ tmp.close()+ out_path = Path(tmp.name)+ with zipfile.ZipFile(input_file) as zin, \+ zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as zout:+ for item in zin.infolist():+ data = patched_xml if item.filename == "word/document.xml" else zin.read(item.filename)+ zout.writestr(item, data)+ return out_path, replacements, warnings++def _clean_mammoth_markdown(markdown: str) -> str:"""Remove Mammoth escapes for punctuation that is safe as literal text."""def _repl(match: re.Match[str]) -> str:@@ -821,7 +941,9 @@ def _clean_mammoth_markdown(markdown: str) -> str:# DOCX → Markdown (mammoth)# ─────────────────────────────────────────────────────────────-def _convert_docx(input_file: Path, out_file: Path) -> str:+def _convert_docx(+ input_file: Path, out_file: Path, warnings: list[str] | None = None,+) -> str:try:import mammothexcept ImportError:@@ -887,13 +1009,27 @@ def _convert_docx(input_file: Path, out_file: Path) -> str:if table_injection is not None:table_file, table_replacements = table_injectionmammoth_source = table_file+ chart_file = None+ chart_replacements: dict[str, str] = {}+ chart_injection = _docx_inject_charts_markdown(mammoth_source)+ if chart_injection is not None:+ chart_file, chart_replacements, chart_warnings = chart_injection+ mammoth_source = chart_file+ if warnings is not None:+ warnings.extend(chart_warnings)try:with mammoth_source.open("rb") as f:result = mammoth.convert_to_markdown(f,convert_image=mammoth.images.img_element(_save_image),+ style_map=DOCX_STYLE_MAP,)finally:+ if chart_file is not None:+ try:+ chart_file.unlink()+ except OSError:+ passif table_file is not None:try:table_file.unlink()@@ -908,10 +1044,14 @@ def _convert_docx(input_file: Path, out_file: Path) -> str:markdown = result.valuefor token, table_markdown in table_replacements.items():markdown = markdown.replace(token, table_markdown)+ for token, chart_markdown in chart_replacements.items():+ markdown = markdown.replace(token, chart_markdown)for token, latex in math_replacements.items():markdown = markdown.replace(token, latex)markdown = _html_img_to_md(markdown)markdown = _clean_mammoth_markdown(markdown)+ # A logo set in a heading style is an image, not a heading.+ markdown = re.sub(r"^#{1,6} (!\[[^\]]*\]\([^)]*\))[ \t]*$", r"\1", markdown, flags=re.M)out_file.write_text(markdown, encoding="utf-8")if manifest:@@ -924,9 +1064,13 @@ def _convert_docx(input_file: Path, out_file: Path) -> str:media_dir.rmdir()media_dir = None # type: ignore[assignment]+ if chart_replacements:+ print(f" Charts: {len(chart_replacements)} rendered from their cached data")for msg in result.messages:if msg.type == "warning":print(f" [warn] {msg.message}")+ if warnings is not None:+ warnings.append(msg.message)_report_result(out_file, media_dir)return markdown@@ -1414,8 +1558,9 @@ def convert_to_markdown(input_path: str, output_path: str | None = None) -> str:if suffix in NATIVE_FORMATS:desc = _FORMAT_DESC[suffix]print(f"[INFO] Converting {desc}: {input_file.name}")+ warnings: list[str] = []if suffix == ".docx":- markdown = _convert_docx(input_file, out_file)+ markdown = _convert_docx(input_file, out_file, warnings)elif suffix in (".html", ".htm"):markdown = _convert_html(input_file, out_file)elif suffix == ".epub":@@ -1430,6 +1575,7 @@ def convert_to_markdown(input_path: str, output_path: str | None = None) -> str:markdown_path=out_file,converter="doc_to_md.py",conversion_type=suffix.lstrip("."),+ warnings=warnings,)if profile_path:print(f" Wrote conversion profile -> {profile_path}")diff --git a/skills/ppt-master/scripts/tests/test_dogfood_leaves_fixes.py b/skills/ppt-master/scripts/tests/test_dogfood_leaves_fixes.pyindex 8569a83f..32b9d44d 100644--- a/skills/ppt-master/scripts/tests/test_dogfood_leaves_fixes.py+++ b/skills/ppt-master/scripts/tests/test_dogfood_leaves_fixes.py@@ -13,6 +13,7 @@ import jsonimport sysimport tempfileimport unittest+import zipfilefrom pathlib import Pathfrom xml.etree import ElementTree as ET@@ -24,6 +25,7 @@ if str(BACKEND_DIR) not in sys.path:sys.path.insert(0, str(BACKEND_DIR))import pdf_to_md # noqa: E402+import doc_to_md # noqa: E402import web_to_md # noqa: E402from svg_to_pptx.drawingml.converter import convert_svg_to_slide_shapes # noqa: E402from svg_to_pptx.drawingml.utils import project_filter_errors # noqa: E402@@ -335,6 +337,66 @@ class TraditionalChineseIntakeTests(unittest.TestCase):self.assertEqual(profile["source"]["url"], "https://example.gov.tw/report.pdf")+class DocxIntakeTests(unittest.TestCase):+ W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"+ DOCUMENT = (+ '<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" '+ 'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" '+ 'xmlns:c="http://schemas.openxmlformats.org/drawingml/2006/chart"><w:body>'+ '<w:p><w:r><w:drawing><c:chart r:id="rId9"/></w:drawing></w:r></w:p>'+ '<w:tbl><w:tr><w:tc><w:p><w:r><w:t>Bar queues</w:t></w:r>'+ '<w:r><w:footnoteReference w:id="2"/></w:r></w:p></w:tc></w:tr></w:tbl>'+ '</w:body></w:document>'+ )+ RELS = (+ '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'+ '<Relationship Id="rId9" Type="chart" Target="charts/chart1.xml"/></Relationships>'+ )+ CHART = (+ '<c:chartSpace xmlns:c="http://schemas.openxmlformats.org/drawingml/2006/chart">'+ '<c:chart><c:plotArea><c:barChart><c:barDir val="col"/><c:grouping val="clustered"/>'+ '<c:ser><c:idx val="0"/><c:order val="0"/>'+ '<c:cat><c:strRef><c:strCache><c:ptCount val="2"/>'+ '<c:pt idx="0"><c:v>2022/23</c:v></c:pt><c:pt idx="1"><c:v>2023/24</c:v></c:pt>'+ '</c:strCache></c:strRef></c:cat>'+ '<c:val><c:numRef><c:numCache><c:ptCount val="2"/>'+ '<c:pt idx="0"><c:v>702</c:v></c:pt><c:pt idx="1"><c:v>659</c:v></c:pt>'+ '</c:numCache></c:numRef></c:val></c:ser></c:barChart></c:plotArea></c:chart></c:chartSpace>'+ )+ FOOTNOTES = (+ '<w:footnotes xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">'+ '<w:footnote w:type="separator" w:id="-1"><w:p/></w:footnote>'+ '<w:footnote w:id="2"><w:p><w:r><w:t>Theatre closed until Winter 2026.</w:t></w:r></w:p>'+ '</w:footnote></w:footnotes>'+ )++ def _docx(self, root: Path) -> Path:+ path = root / "report.docx"+ with zipfile.ZipFile(path, "w") as docx:+ docx.writestr("word/document.xml", self.DOCUMENT)+ docx.writestr("word/_rels/document.xml.rels", self.RELS)+ docx.writestr("word/charts/chart1.xml", self.CHART)+ docx.writestr("word/footnotes.xml", self.FOOTNOTES)+ return path++ def test_embedded_chart_cache_becomes_a_table(self) -> None:+ with tempfile.TemporaryDirectory() as tmp:+ patched, replacements, warnings = doc_to_md._docx_inject_charts_markdown(+ self._docx(Path(tmp)))+ patched.unlink()+ [markdown] = replacements.values()+ self.assertIn("| 2023/24 | 659 |", markdown)+ self.assertEqual(warnings, [])++ def test_table_cell_footnote_survives(self) -> None:+ with tempfile.TemporaryDirectory() as tmp:+ patched, replacements = doc_to_md._docx_inject_tables_markdown(self._docx(Path(tmp)))+ patched.unlink()+ [markdown] = replacements.values()+ self.assertIn("Bar queues[^2]", markdown)+ self.assertIn("[^2]: Theatre closed until Winter 2026.", markdown)++class SlideSizeTypeTests(unittest.TestCase):def test_standard_ratios_keep_their_token(self) -> None:self.assertEqual(_slide_size_type(12192000, 6858000), "screen16x9")diff --git a/skills/ppt-master/scripts/tests/test_source_to_md_cli.py b/skills/ppt-master/scripts/tests/test_source_to_md_cli.pyindex 4d1a4723..4ad0d9ac 100644--- a/skills/ppt-master/scripts/tests/test_source_to_md_cli.py+++ b/skills/ppt-master/scripts/tests/test_source_to_md_cli.py@@ -372,7 +372,8 @@ class SourceCollisionTests(unittest.TestCase):if encoding == "utf-8":self.assertEqual(profile["warnings"], [])else:- self.assertIn(encoding, result.stdout)+ # --json keeps stdout machine-readable; the notice is on stderr.+ self.assertIn(encoding, result.stderr)self.assertIn(encoding, " ".join(profile["warnings"]))def test_invalid_passthrough_fails_before_writing_outputs(self) -> None: