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

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.md
index 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 Art
Hybrid 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.md
index 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 `&amp;` and `&lt;`); 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.py
index 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 argparse
import filecmp
import json
import os
+import stat
import re
import shutil
import 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 & ~umask
fd, 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.py
index 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 1
profile = 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 0
diff --git a/skills/ppt-master/scripts/source_to_md/doc_to_md.py b/skills/ppt-master/scripts/source_to_md/doc_to_md.py
index 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 None
try:
@@ -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 mammoth
except 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_injection
mammoth_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:
+ pass
if 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.value
for 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.py
index 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 json
import sys
import tempfile
import unittest
+import zipfile
from pathlib import Path
from 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: E402
import web_to_md # noqa: E402
from svg_to_pptx.drawingml.converter import convert_svg_to_slide_shapes # noqa: E402
from 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.py
index 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: