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(ppt_to_md): preserve source-deck hyperlinks in Markdown extraction
hugohe37660577e0ca7
diff --git a/skills/ppt-master/scripts/source_to_md/ppt_to_md.py b/skills/ppt-master/scripts/source_to_md/ppt_to_md.pyindex 942dd058..e6844001 100644--- a/skills/ppt-master/scripts/source_to_md/ppt_to_md.py+++ b/skills/ppt-master/scripts/source_to_md/ppt_to_md.py@@ -7,8 +7,18 @@ Open XML PowerPoint files into Markdown.Primary use case: PPTX source decks -> Markdown for PPT generation input.+Hyperlinks present in the source deck are preserved: run-level external URLs+and slide-internal jumps are emitted as ``[text](url)`` / ``[text](#slide-N)``,+with a shape-level ``click_action`` fallback.+Dependency:pip install python-pptx++API stability note:+ Detecting slide-internal jumps (``ppaction://hlinksldjump``) reads+ ``run._r`` (the CT_TextRun lxml element) because python-pptx exposes no+ public API to distinguish an internal jump from an external URL. This+ access pattern is stable across python-pptx 0.6.x; pin python-pptx<0.7."""from __future__ import annotations@@ -22,8 +32,10 @@ import sysfrom dataclasses import dataclassfrom io import BytesIOfrom pathlib import Path+from urllib.parse import quotefrom pptx import Presentation+from pptx.enum.action import PP_ACTIONfrom pptx.enum.shapes import MSO_SHAPE_TYPEfrom pptx.oxml.ns import qn@@ -43,6 +55,11 @@ IMAGE_EXT_BY_CONTENT_TYPE = {}LEGACY_GENERATED_IMAGE_RE = re.compile(r"^slide_\d{2}_image_\d{2}\.[A-Za-z0-9]+$")+# Hyperlink schemes dropped during extraction (a blacklist of known-dangerous+# schemes). PowerPoint also rejects unrecognized schemes at open time, so the+# residual risk from schemes not listed here is low.+UNSUPPORTED_URL_SCHEMES = ("javascript:", "data:", "vbscript:", "file:")+SUPPORTED_FORMATS = {".pptx": "PowerPoint Presentation",@@ -135,12 +152,164 @@ def iter_leaf_shapes(shapes: object) -> list[LeafShape]:return items-def text_frame_to_markdown(text_frame: object) -> str:- """Convert a PowerPoint text frame into Markdown."""- paragraphs = []+def _is_supported_url(url: str) -> bool:+ """Reject empty URLs and the known-dangerous schemes."""+ return bool(url) and not any(+ url.lower().startswith(scheme) for scheme in UNSUPPORTED_URL_SCHEMES+ )+++def _escape_md_link_text(text: str) -> str:+ """Backslash-escape characters that would break a Markdown link label.++ A stray ``]`` in anchor text would otherwise close the ``[...]`` early.+ """+ return text.replace("\\", "\\\\").replace("[", "\\[").replace("]", "\\]")+++def _encode_md_url(url: str) -> str:+ """Percent-encode a URL so Markdown link syntax stays unambiguous.++ Notably encodes ``(`` / ``)`` to ``%28`` / ``%29`` so a parenthesised URL+ does not terminate the ``[text](url)`` form early.+ """+ return quote(url, safe="/:?=&%#@!$'*+,;")+++def _resolve_internal_jump(run: object, shape: object) -> str | None:+ """Return ``#slide-N`` for a run carrying a slide-internal jump, else None.++ Reads ``run._r`` (private python-pptx API) because the public+ ``run.hyperlink.address`` cannot tell an internal jump apart from an+ external URL — see the module docstring's API stability note.+ """+ r_id = ""+ try:+ rpr = run._r.find(qn("a:rPr"))+ if rpr is None:+ return None+ hlink = rpr.find(qn("a:hlinkClick"))+ if hlink is None or "hlinksldjump" not in (hlink.get("action", "") or ""):+ return None+ r_id = hlink.get(qn("r:id"), "")+ if not r_id:+ return None+ target_slide = shape.part.related_part(r_id).slide+ prs = shape.part.slide.part.package.presentation_part.presentation+ return f"#slide-{list(prs.slides).index(target_slide) + 1}"+ except (KeyError, ValueError, AttributeError):+ print(f"[WARN] ppt_to_md: could not resolve slide jump rId={r_id}", file=sys.stderr)+ return None+++def _run_url(run: object, shape: object) -> str | None:+ """Resolve a run's hyperlink target to a markdown-ready URL, or None."""+ if shape is not None:+ internal = _resolve_internal_jump(run, shape)+ if internal:+ return internal+ try:+ addr = run.hyperlink.address+ except AttributeError:+ return None+ if _is_supported_url(addr or ""):+ return _encode_md_url(addr)+ return None+++def _paragraph_to_markdown(paragraph: object, shape: object) -> str:+ """Render one paragraph, merging consecutive runs that share a URL.++ Run text is concatenated verbatim — including the spaces between runs — and+ normalized only once over the assembled paragraph, so a link in the middle+ of a sentence does not swallow its surrounding spaces. A link group's own+ leading / trailing whitespace is kept outside the ``[...]`` so it separates+ words rather than padding the anchor text.+ """+ parts = []+ current_url = None+ current_text = ""++ def flush():+ if not current_text:+ return+ if current_url is None:+ parts.append(current_text)+ return+ lead = current_text[: len(current_text) - len(current_text.lstrip())]+ trail = current_text[len(current_text.rstrip()):]+ core = current_text.strip()+ display = _escape_md_link_text(core) if core else current_url+ parts.append(f"{lead}[{display}]({current_url}){trail}")++ has_run_hyperlink = False+ for run in paragraph.runs:+ url = _run_url(run, shape)+ if url:+ has_run_hyperlink = True+ if url != current_url:+ flush()+ current_text = ""+ current_url = url+ current_text += run.text or ""+ flush()++ text = normalize_text("".join(parts))++ # Shape-level click_action only matters when no run carried its own link.+ if not has_run_hyperlink and shape is not None:+ text = _apply_shape_click_action(text, shape)+ return text+++def _apply_shape_click_action(text: str, shape: object) -> str:+ """Wrap paragraph text in a link from the shape's click_action, if any."""+ try:+ action = shape.click_action+ if action.action == PP_ACTION.HYPERLINK:+ url = action.hyperlink.address or ""+ if _is_supported_url(url):+ return f"[{_escape_md_link_text(text)}]({_encode_md_url(url)})"+ elif action.action == PP_ACTION.NAMED_SLIDE:+ target = action.target_slide+ if target is not None:+ prs = shape.part.slide.part.package.presentation_part.presentation+ idx = list(prs.slides).index(target) + 1+ return f"[{_escape_md_link_text(text)}](#slide-{idx})"+ except (AttributeError, ValueError):+ print("[WARN] ppt_to_md: could not process shape click_action", file=sys.stderr)+ return text+++def _paragraph_has_hyperlink(paragraph: object) -> bool:+ """True if any run carries an external URL or an internal slide jump."""+ for run in paragraph.runs:+ try:+ if run.hyperlink.address:+ return True+ except AttributeError:+ pass+ try:+ rpr = run._r.find(qn("a:rPr"))+ if rpr is not None and rpr.find(qn("a:hlinkClick")) is not None:+ return True+ except AttributeError:+ continue+ return False+++def text_frame_to_markdown(text_frame: object, shape: object = None) -> str:+ """Convert a PowerPoint text frame into Markdown, preserving hyperlinks.++ Run-level external URLs and slide-internal jumps are emitted as+ ``[text](url)`` / ``[text](#slide-N)``; consecutive runs sharing a URL are+ merged. When no run carries a link, the shape's ``click_action`` is used as+ a paragraph-level fallback. Pass ``shape`` to enable hyperlink extraction;+ without it the frame degrades to plain text.+ """visible_paragraphs = [paragraph for paragraph in text_frame.paragraphs- if normalize_text(paragraph.text)+ if normalize_text(paragraph.text) or _paragraph_has_hyperlink(paragraph)]if not visible_paragraphs:return ""@@ -149,8 +318,9 @@ def text_frame_to_markdown(text_frame: object) -> str:if not list_like:list_like = len(visible_paragraphs) > 1+ paragraphs = []for paragraph in visible_paragraphs:- text = normalize_text(paragraph.text)+ text = _paragraph_to_markdown(paragraph, shape)if not text:continueif list_like:@@ -434,7 +604,7 @@ def extract_notes(slide: object) -> str:shape = item.shapeif not getattr(shape, "has_text_frame", False):continue- text = text_frame_to_markdown(shape.text_frame)+ text = text_frame_to_markdown(shape.text_frame, shape)if text:blocks.append(text)@@ -534,7 +704,7 @@ def convert_presentation_to_markdown(continueif getattr(shape, "has_text_frame", False):- text_md = text_frame_to_markdown(shape.text_frame)+ text_md = text_frame_to_markdown(shape.text_frame, shape)if text_md:blocks.append(text_md)continue