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(source-to-md): batch/directory conversion + web title naming

hugohe3088450db3275
diff --git a/AGENTS.md b/AGENTS.md
index db558f38..2f5513fd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,11 +43,11 @@ Convenience summary only — full workflow in [`skills/ppt-master/SKILL.md`](ski
```bash
# Source content conversion
-python3 skills/ppt-master/scripts/source_to_md.py <file_or_URL> [<file_or_URL> ...]
+python3 skills/ppt-master/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]
# Project management
python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169
-python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_URLs...> --move
+python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs_or_URLs...> --move
python3 skills/ppt-master/scripts/project_manager.py validate <project_path>
# Icon selection — copy chosen library icons into <project>/icons/ (missing names reported + non-zero = re-pick)
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index ca2ec66e..a1e476ae 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -136,15 +136,15 @@ routes by source type, and writes the standard Markdown plus conversion profile.
| User Provides | Action |
|---------------|--------|
-| PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL> [<file_or_URL> ...]` |
+| PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]` |
| CSV / TSV | Read directly as plain-text table source |
| Markdown | Read directly |
For PPTX sources, Step 1 converts the deck to Markdown content; after Step 2
`import-sources`, standard PPTX intake is also written to `<project>/analysis/`.
-Use `source_to_md.py -t <type>` only when extension detection is ambiguous. Use
-`-o` only with a single input; explicit multi-input conversion writes one
-Markdown/profile pair per source. Backend converter details are documented in
+Use `source_to_md.py -t <type>` only when extension detection is ambiguous. With
+multiple inputs or directory inputs, `-o` is an output directory and conversion
+writes one Markdown/profile pair per source. Backend converter details are documented in
[`scripts/docs/conversion.md`](scripts/docs/conversion.md).
> **Office vector assets (EMF/WMF) from DOCX/PPTX sources**:
@@ -179,7 +179,7 @@ Import source content (choose based on the situation):
| Situation | Action |
|-----------|--------|
-| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --move` |
+| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --move` |
| User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly |
For PPTX sources, `import-sources` automatically runs the standard intake enrichment:
@@ -192,7 +192,7 @@ For each PPTX it writes `<stem>.identity.json` (canvas, theme palette/fonts, obs
Multi-deck: several PPTX files may be imported into one main-pipeline project — each gets its own `<stem>.*` artifacts and a deck entry in `source_profile.json`. `source_profile.json` stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The beautify / template-fill workflows remain single-deck (1:1 to one chosen source deck) and read that deck's `<stem>.*` artifacts.
-> ⚠️ **MUST use `--move`** (not copy): all source files — Step 1's generated Markdown, original PDFs / MDs / images — go into `sources/` via `import-sources --move`. After execution they no longer exist at the original location. Intermediate artifacts (e.g., `_files/`) are handled automatically.
+> ⚠️ **MUST use `--move`** (not copy): all source files — Step 1's generated Markdown, original PDFs / MDs / images — go into `sources/` via `import-sources --move`. Pass both the original source path(s)/directory and the Step 1 Markdown output path(s)/directory. After execution they no longer exist at the original location. Intermediate artifacts (e.g., `_files/`) are handled automatically.
**✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.**
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index ec9c0e0a..8fca4444 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -6,7 +6,7 @@ This directory contains user-facing scripts for conversion, project setup, direc
- Top-level `scripts/`: runnable entry scripts
- `scripts/source_to_md.py`: unified source-document → Markdown dispatcher
-- `scripts/source_to_md/`: source-document → Markdown routing helpers and backend converters (`_dispatcher.py`, `pdf_to_md.py`, `doc_to_md.py`, `excel_to_md.py`, `ppt_to_md.py`, `web_to_md.py`)
+- `scripts/source_to_md/`: source-document → Markdown routing/batch helpers and backend converters (`_dispatcher.py`, `_batch.py`, `pdf_to_md.py`, `doc_to_md.py`, `excel_to_md.py`, `ppt_to_md.py`, `web_to_md.py`)
- `scripts/image_backends/`: internal provider implementations used by `image_gen.py`
- `scripts/tts_backends/`: internal TTS provider implementations used by `notes_to_audio.py`
- `scripts/template_import/`: internal PPTX reference-preparation helpers used by `pptx_template_import.py`
@@ -19,14 +19,14 @@ This directory contains user-facing scripts for conversion, project setup, direc
Typical end-to-end workflow:
```bash
-python3 scripts/source_to_md.py <file-or-url> [<file-or-url> ...]
+python3 scripts/source_to_md.py <file-or-url-or-dir> [<file-or-url-or-dir> ...]
# or direct backend calls:
python3 scripts/source_to_md/pdf_to_md.py <file.pdf>
# or
python3 scripts/source_to_md/ppt_to_md.py <deck.pptx>
python3 scripts/source_to_md/excel_to_md.py <workbook.xlsx>
python3 scripts/project_manager.py init <project_name> --format ppt169
-python3 scripts/project_manager.py import-sources <project_path> <source_files...> --move
+python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --move
python3 scripts/total_md_split.py <project_path>
python3 scripts/finalize_svg.py <project_path>
python3 scripts/animation_config.py scaffold <project_path> # optional object-level animation overrides
@@ -56,7 +56,7 @@ python3 scripts/update_repo.py
Conversion:
```bash
-python3 scripts/source_to_md.py <file-or-url> [<file-or-url> ...]
+python3 scripts/source_to_md.py <file-or-url-or-dir> [<file-or-url-or-dir> ...]
python3 scripts/source_to_md/pdf_to_md.py <file.pdf>
python3 scripts/source_to_md/ppt_to_md.py <deck.pptx>
python3 scripts/source_to_md/doc_to_md.py <file.docx>
@@ -68,7 +68,7 @@ Project setup:
```bash
python3 scripts/project_manager.py init <project_name> --format ppt169
-python3 scripts/project_manager.py import-sources <project_path> <source_files...> --move
+python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --move
python3 scripts/project_manager.py validate <project_path>
```
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index 338b5fe1..a8996cfb 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -36,6 +36,7 @@ Routing is centralized in `source_to_md/_dispatcher.py` and reused by
```bash
python3 scripts/source_to_md.py paper.pdf
python3 scripts/source_to_md.py paper.pdf report.docx deck.pptx
+python3 scripts/source_to_md.py ./sources -o ./markdown
python3 scripts/source_to_md.py ./pdfs/*.pdf
python3 scripts/source_to_md.py ./decks/*.pptx
python3 scripts/source_to_md.py report.docx -o report.md
@@ -54,16 +55,12 @@ Useful options:
existing PDF image mode. They are intentionally PDF-only until other backends
expose the same behavior natively.
- Unknown backend-specific flags are passed through to each selected converter.
-- `-o/--output` is valid only with one input. Multiple explicit inputs write
- one Markdown/profile pair per source.
+- `-o/--output` selects one Markdown file for one input, or an output directory
+ for multiple inputs / directory inputs.
For multi-source project intake, use `project_manager.py import-sources` with
-all source paths / URLs. `source_to_md.py` intentionally rejects directory
-batching; pass explicit files/URLs or use project intake.
-
-Backend converters are single-file tools. For ad hoc multi-file conversion,
-pass explicit files or shell-expanded globs to `source_to_md.py`; for project
-intake, use `project_manager.py import-sources`.
+all source paths / URLs. `source_to_md.py` and the backend converters support
+single files, explicit multi-file inputs, and non-recursive directory inputs.
## `source_to_md/pdf_to_md.py`
@@ -72,6 +69,8 @@ Recommended first choice for native PDFs.
```bash
python3 scripts/source_to_md/pdf_to_md.py book.pdf
python3 scripts/source_to_md/pdf_to_md.py book.pdf -o output.md
+python3 scripts/source_to_md/pdf_to_md.py book.pdf appendix.pdf
+python3 scripts/source_to_md/pdf_to_md.py ./pdfs -o ./markdown
# Image extraction control (default: filtered)
python3 scripts/source_to_md/pdf_to_md.py book.pdf --images filtered # size/quality filters applied
@@ -111,6 +110,8 @@ Pandoc fallback (only if you need these):
```bash
python3 scripts/source_to_md/doc_to_md.py lecture.docx
python3 scripts/source_to_md/doc_to_md.py lecture.docx -o output.md
+python3 scripts/source_to_md/doc_to_md.py lecture.docx notes.html
+python3 scripts/source_to_md/doc_to_md.py ./docs -o ./markdown
python3 scripts/source_to_md/doc_to_md.py notes.epub
python3 scripts/source_to_md/doc_to_md.py paper.tex -o paper.md # uses pandoc
```
@@ -144,6 +145,8 @@ Unsupported by default:
```bash
python3 scripts/source_to_md/excel_to_md.py report.xlsx
python3 scripts/source_to_md/excel_to_md.py report.xlsx -o output.md
+python3 scripts/source_to_md/excel_to_md.py report.xlsx budget.xlsm
+python3 scripts/source_to_md/excel_to_md.py ./workbooks -o ./markdown
python3 scripts/source_to_md/excel_to_md.py report.xlsm --max-rows 200 --max-cols 40
```
@@ -175,6 +178,8 @@ Supported formats include:
```bash
python3 scripts/source_to_md/ppt_to_md.py sales_deck.pptx
python3 scripts/source_to_md/ppt_to_md.py sales_deck.pptx -o output.md
+python3 scripts/source_to_md/ppt_to_md.py sales_deck.pptx appendix.pptx
+python3 scripts/source_to_md/ppt_to_md.py ./decks -o ./markdown
python3 scripts/source_to_md/ppt_to_md.py template.ppsx -o notes/template.md
```
@@ -225,6 +230,7 @@ python3 scripts/source_to_md/web_to_md.py https://example.com/article
python3 scripts/source_to_md/web_to_md.py https://url1.com https://url2.com
python3 scripts/source_to_md/web_to_md.py -f urls.txt
python3 scripts/source_to_md/web_to_md.py https://example.com -o output.md
+python3 scripts/source_to_md/web_to_md.py https://example.com --emit-result /tmp/result.json
```
When `curl_cffi` is installed (included in `requirements.txt`), this script
@@ -235,6 +241,8 @@ block Python's default TLS fingerprint. No extra flags needed. If
On success, the converter writes `<output>.conversion_profile.json` beside the
Markdown output.
+`--emit-result` is for wrapper scripts that need the actual saved Markdown path
+when the converter derives a title-based filename.
## `rotate_images.py`
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index b31829d4..97630686 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -10,7 +10,7 @@ Main entry point for project setup and validation.
```bash
python3 scripts/project_manager.py init <project_name> --format ppt169
-python3 scripts/project_manager.py import-sources <project_path> <source1> [<source2> ...]
+python3 scripts/project_manager.py import-sources <project_path> <source1_or_dir> [<source2_or_dir> ...]
python3 scripts/project_manager.py validate <project_path>
python3 scripts/project_manager.py info <project_path>
```
@@ -18,6 +18,9 @@ python3 scripts/project_manager.py info <project_path>
Notes:
- Files outside the repo are copied into `sources/` by default
- With `--move`, files outside the repo are moved into `sources/`
+- Directory inputs are expanded non-recursively. After Step 1 conversion,
+ pass both the original source file/directory and the generated Markdown
+ file/directory so both are archived under `sources/`.
- Files already inside the repo are moved into `sources/` by default (with a stderr
note), to avoid leaving unintended artifacts that could be committed by mistake.
Pass `--copy` to force a copy for in-repo sources instead.
diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.py
index 72ad4fc6..bff93017 100644
--- a/skills/ppt-master/scripts/project_manager.py
+++ b/skills/ppt-master/scripts/project_manager.py
@@ -612,16 +612,37 @@ class ProjectManager:
"notes": [],
"skipped": [],
}
+
+ expanded_items: list[str] = []
+ for item in source_items:
+ if is_url(item):
+ expanded_items.append(item)
+ continue
+ item_path = Path(item)
+ if item_path.is_dir():
+ directory_files = sorted(
+ path for path in item_path.iterdir() if path.is_file()
+ )
+ if directory_files:
+ expanded_items.extend(str(path) for path in directory_files)
+ summary["notes"].append(
+ f"{item}: expanded directory into {len(directory_files)} file(s)"
+ )
+ else:
+ summary["skipped"].append(f"{item}: directory contains no files")
+ continue
+ expanded_items.append(item)
+
explicit_markdown_stems = {
Path(item).stem
- for item in source_items
+ for item in expanded_items
if not is_url(item)
and Path(item).exists()
and Path(item).is_file()
and Path(item).suffix.lower() in {".md", ".markdown"}
}
- for item in source_items:
+ for item in expanded_items:
if is_url(item):
markdown_path = self._ensure_unique_path(
sources_dir / f"{derive_url_basename(item)}.md"
@@ -861,7 +882,7 @@ def build_parser() -> argparse.ArgumentParser:
help="Import source files or URLs into a project",
)
import_sources.add_argument("project_path", help="Project directory")
- import_sources.add_argument("sources", nargs="+", help="Source files or URLs")
+ import_sources.add_argument("sources", nargs="+", help="Source files, directories, or URLs")
mode = import_sources.add_mutually_exclusive_group()
mode.add_argument("--move", action="store_true", help="Move local source files")
mode.add_argument("--copy", action="store_true", help="Copy local source files")
diff --git a/skills/ppt-master/scripts/source_to_md.py b/skills/ppt-master/scripts/source_to_md.py
index 31574885..68bb3d93 100644
--- a/skills/ppt-master/scripts/source_to_md.py
+++ b/skills/ppt-master/scripts/source_to_md.py
@@ -5,11 +5,12 @@ PPT Master - Unified Markdown Converter
Auto-detect source type and dispatch to the existing source_to_md converters.
Usage:
- python3 scripts/source_to_md.py <file_or_url> [<file_or_url> ...] [options]
+ python3 scripts/source_to_md.py <file_or_url_or_dir> [<file_or_url_or_dir> ...] [options]
Examples:
python3 scripts/source_to_md.py paper.pdf
python3 scripts/source_to_md.py paper.pdf report.docx deck.pptx
+ python3 scripts/source_to_md.py ./sources -o ./markdown
python3 scripts/source_to_md.py report.docx -o report.md
python3 scripts/source_to_md.py deck.pptx --json
@@ -21,11 +22,10 @@ from __future__ import annotations
import argparse
import json
-import re
import subprocess
import sys
+import tempfile
from pathlib import Path
-from urllib.parse import urlparse
_SCRIPTS_DIR = Path(__file__).resolve().parent
if str(_SCRIPTS_DIR) not in sys.path:
@@ -42,6 +42,7 @@ from _conversion_profile import ( # noqa: E402
profile_path_for,
write_conversion_profile,
)
+from _batch import expand_directory_inputs, unique_output_path # noqa: E402
from _dispatcher import ( # noqa: E402
build_conversion_command,
default_markdown_path,
@@ -60,23 +61,34 @@ def _print_status(message: str) -> None:
print(message, file=sys.stderr)
-def _sanitize_output_stem(value: str) -> str:
- safe = re.sub(r"[^A-Za-z0-9_.-]+", "_", value.strip())
- safe = safe.strip("._-")
- while "__" in safe:
- safe = safe.replace("__", "_")
- return safe[:120] or "web_source"
+def _is_supported_directory_item(path: Path) -> bool:
+ return detect_source_type(str(path)) in {
+ "pdf", "doc", "excel", "pptx", "markdown", "text",
+ }
-def _default_batch_output(input_arg: str, conversion_type: str) -> str | None:
- """Return a deterministic per-source output path for batch mode."""
- if conversion_type == "web":
- parsed = urlparse(input_arg)
- parts = [parsed.netloc]
- if parsed.path and parsed.path != "/":
- parts.append(parsed.path.strip("/").replace("/", "_"))
- return str(Path(f"{_sanitize_output_stem('_'.join(parts))}.md"))
- return str(default_markdown_path(input_arg))
+def _dispatch_output_arg(
+ input_arg: str,
+ conversion_type: str,
+ output_arg: str | None,
+ batch_mode: bool,
+ used_outputs: set[Path],
+) -> str | None:
+ if output_arg and batch_mode and conversion_type == "web":
+ return None
+ if output_arg and batch_mode:
+ return str(
+ unique_output_path(
+ Path(output_arg),
+ default_markdown_path(input_arg).stem,
+ used_outputs,
+ )
+ )
+ if output_arg:
+ return output_arg
+ if batch_mode and conversion_type != "web":
+ return str(default_markdown_path(input_arg))
+ return None
def run_backend(command: list[str], script_name: str) -> int:
@@ -176,6 +188,15 @@ def print_json_result(
print(json.dumps(payload, ensure_ascii=False))
+def _read_emit_result(path: Path) -> Path | None:
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError):
+ return None
+ markdown = payload.get("markdown")
+ return Path(markdown) if isinstance(markdown, str) and markdown else None
+
+
def _pdf_image_mode(args: argparse.Namespace) -> str | None:
image_mode = args.images
if args.no_images:
@@ -202,19 +223,12 @@ def dispatch_single(
output_arg: str | None,
args: argparse.Namespace,
unknown_args: list[str],
+ web_output_dir: str | None = None,
) -> int:
"""Dispatch one source to the matching existing converter."""
if conversion_type == "auto":
conversion_type = detect_source_type(input_arg)
- if conversion_type == "directory":
- print(
- "[ERROR] Directories are not supported by source_to_md.py; "
- "use project_manager.py import-sources for multi-source project intake.",
- file=sys.stderr,
- )
- return 1
-
if conversion_type == "markdown":
output = resolve_output(output_arg, input_arg)
return write_passthrough(input_arg, output, "markdown", args.json)
@@ -224,25 +238,51 @@ def dispatch_single(
if conversion_type == "web":
output = Path(output_arg) if output_arg else None
+ emit_result: Path | None = None
+ extra_args = list(unknown_args)
+ if output is None:
+ emit_file = tempfile.NamedTemporaryFile(
+ prefix="ppt-master-web-result-",
+ suffix=".json",
+ delete=False,
+ )
+ emit_file.close()
+ emit_result = Path(emit_file.name)
+ extra_args.extend(["--emit-result", str(emit_result)])
+ if web_output_dir:
+ extra_args.extend(["--dir", web_output_dir])
try:
route = build_conversion_command(
input_arg,
output,
forced_type="web",
- extra_args=unknown_args,
+ extra_args=extra_args,
)
except ValueError as exc:
+ if emit_result:
+ emit_result.unlink(missing_ok=True)
print(f"[ERROR] {exc}", file=sys.stderr)
return 1
rc = run_backend(route.command, route.script_name)
if rc != 0:
+ if emit_result:
+ emit_result.unlink(missing_ok=True)
return rc
- if route.output_path and route.output_path.is_file():
- profile = ensure_profile(input_arg, route.output_path, route.script_name, "web")
- print_output(route.output_path)
+ output_path = route.output_path
+ if output_path is None and emit_result is not None:
+ output_path = _read_emit_result(emit_result)
+ 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 args.json:
- print_json_result(input_arg, route.output_path, route.script_name, "web", profile)
- return 0
+ print_json_result(input_arg, output_path, route.script_name, "web", profile)
+ return 0
+ if output is not None:
+ print(f"[ERROR] Expected Markdown output not found: {output}", file=sys.stderr)
+ else:
+ print("[ERROR] Web conversion did not report a Markdown output path", file=sys.stderr)
+ return 1
if conversion_type not in {"pdf", "doc", "excel", "pptx"}:
print(
@@ -291,6 +331,7 @@ def build_parser() -> argparse.ArgumentParser:
Examples:
python3 scripts/source_to_md.py paper.pdf
python3 scripts/source_to_md.py paper.pdf report.docx deck.pptx
+ python3 scripts/source_to_md.py ./sources -o ./markdown
python3 scripts/source_to_md.py report.docx -o output.md
python3 scripts/source_to_md.py deck.pptx --json
python3 scripts/source_to_md.py https://example.com/article -o article.md
@@ -299,7 +340,7 @@ Backend-specific flags not listed here are passed through to the selected
converter, so existing converter behavior remains the source of truth.
""",
)
- parser.add_argument("inputs", nargs="+", help="Input file(s) or URL(s)")
+ parser.add_argument("inputs", nargs="+", help="Input file(s), directories, or URL(s)")
parser.add_argument(
"-t",
"--type",
@@ -307,7 +348,11 @@ converter, so existing converter behavior remains the source of truth.
default="auto",
help="Force a conversion type (default: auto)",
)
- parser.add_argument("-o", "--output", help="Output Markdown file")
+ parser.add_argument(
+ "-o",
+ "--output",
+ help="Output Markdown file for one input, or output directory for multiple inputs/directories",
+ )
parser.add_argument(
"--images",
choices=["all", "filtered", "none"],
@@ -360,31 +405,63 @@ def dispatch_many(
args: argparse.Namespace,
unknown_args: list[str],
conversion_types: list[str],
+ batch_mode: bool = False,
+ initial_failures: list[str] | None = None,
) -> int:
success_count = 0
- failed: list[tuple[str, int]] = []
- batch_mode = len(inputs) > 1
+ failed: list[str] = []
+ skipped: list[str] = list(initial_failures or [])
+ batch_mode = batch_mode or len(inputs) > 1
+ if args.output and batch_mode:
+ output_dir = Path(args.output)
+ if output_dir.exists() and not output_dir.is_dir():
+ print(f"[ERROR] Batch output path is not a directory: {args.output}", file=sys.stderr)
+ return 1
+ output_dir.mkdir(parents=True, exist_ok=True)
+ used_outputs: set[Path] = set()
for input_arg, conversion_type in zip(inputs, conversion_types):
- output_arg = args.output
+ output_arg = _dispatch_output_arg(
+ input_arg,
+ conversion_type,
+ args.output,
+ batch_mode,
+ used_outputs,
+ )
+ web_output_dir = (
+ args.output
+ if args.output and batch_mode and conversion_type == "web"
+ else None
+ )
if batch_mode:
- output_arg = _default_batch_output(input_arg, conversion_type)
_print_status(f"\n==> {input_arg}")
- rc = dispatch_single(input_arg, conversion_type, output_arg, args, unknown_args)
+ rc = dispatch_single(
+ input_arg,
+ conversion_type,
+ output_arg,
+ args,
+ unknown_args,
+ web_output_dir=web_output_dir,
+ )
if rc == 0:
success_count += 1
else:
- failed.append((input_arg, rc))
+ failed.append(f"{input_arg}: exit {rc}")
if batch_mode:
_print_status(f"\n[Done] Success: {success_count}/{len(inputs)}, Failed: {len(failed)}")
+ if skipped:
+ _print_status("\n[Skipped directories]:")
+ for item in skipped:
+ _print_status(f" - {item}")
if failed:
_print_status("\n[Failed inputs]:")
- for input_arg, rc in failed:
- _print_status(f" - {input_arg}: exit {rc}")
- return 1
- return 0 if not failed else failed[0][1]
+ for item in failed:
+ _print_status(f" - {item}")
+ if not inputs:
+ return 1
+ return 0 if not failed and not skipped else 1
def main(argv: list[str] | None = None) -> int:
@@ -394,11 +471,14 @@ def main(argv: list[str] | None = None) -> int:
if not _validate_image_options(args):
return 2
- if len(args.inputs) > 1 and args.output:
- print("[ERROR] -o/--output is only valid with a single input", file=sys.stderr)
- return 2
+ inputs, expansion_errors, saw_directory = expand_directory_inputs(
+ args.inputs,
+ _is_supported_directory_item,
+ is_external_ref=is_url,
+ )
+ batch_mode = saw_directory or len(inputs) > 1
- conversion_types = [_conversion_type_for_input(item, args.type) for item in args.inputs]
+ conversion_types = [_conversion_type_for_input(item, args.type) for item in inputs]
if not _validate_pdf_image_flags(args, conversion_types):
return 2
@@ -411,7 +491,14 @@ def main(argv: list[str] | None = None) -> int:
)
return 2
- return dispatch_many(args.inputs, args, unknown_args, conversion_types)
+ return dispatch_many(
+ inputs,
+ args,
+ unknown_args,
+ conversion_types,
+ batch_mode=batch_mode,
+ initial_failures=expansion_errors,
+ )
if __name__ == "__main__":
diff --git a/skills/ppt-master/scripts/source_to_md/_batch.py b/skills/ppt-master/scripts/source_to_md/_batch.py
new file mode 100644
index 00000000..ef98a09f
--- /dev/null
+++ b/skills/ppt-master/scripts/source_to_md/_batch.py
@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+PPT Master - Source Converter Batch Helpers
+
+Share explicit multi-file and directory expansion logic across source_to_md
+backend converters.
+
+Usage:
+ Imported by scripts/source_to_md/*_to_md.py
+
+Examples:
+ run_path_batch(["docs"], {".docx"}, None, convert_one)
+
+Dependencies:
+ None
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+
+ConvertOne = Callable[[Path, Path], bool]
+IsSupportedFile = Callable[[Path], bool]
+
+
+def _print_status(message: str) -> None:
+ print(message, file=sys.stderr)
+
+
+def expand_directory_inputs(
+ inputs: list[str],
+ is_supported_file: IsSupportedFile,
+ is_external_ref: Callable[[str], bool] | None = None,
+) -> tuple[list[str], list[str], bool]:
+ """Expand non-recursive directory inputs while preserving other items."""
+ expanded: list[str] = []
+ errors: list[str] = []
+ saw_directory = False
+ is_external = is_external_ref or (lambda _item: False)
+
+ for item in inputs:
+ if is_external(item):
+ expanded.append(item)
+ continue
+ path = Path(item)
+ if path.is_dir():
+ saw_directory = True
+ matches = sorted(
+ child for child in path.iterdir()
+ if child.is_file() and is_supported_file(child)
+ )
+ if matches:
+ expanded.extend(str(match) for match in matches)
+ else:
+ errors.append(f"{item}: no supported files found")
+ continue
+ expanded.append(item)
+
+ return expanded, errors, saw_directory
+
+
+def _output_key(path: Path) -> Path:
+ return path.resolve(strict=False)
+
+
+def unique_output_path(output_dir: Path, stem: str, used_outputs: set[Path]) -> Path:
+ """Return an in-run unique Markdown path without consulting the filesystem."""
+ base = stem or "output"
+ candidate = output_dir / f"{base}.md"
+ suffix = 2
+ while _output_key(candidate) in used_outputs:
+ candidate = output_dir / f"{base}_{suffix}.md"
+ suffix += 1
+ used_outputs.add(_output_key(candidate))
+ return candidate
+
+
+def _output_for(
+ source: Path,
+ output_arg: str | None,
+ batch_mode: bool,
+ used_outputs: set[Path],
+) -> Path:
+ if output_arg and batch_mode:
+ return unique_output_path(Path(output_arg), source.stem, used_outputs)
+ if output_arg:
+ return Path(output_arg)
+ return source.with_suffix(".md")
+
+
+def run_path_batch(
+ inputs: list[str],
+ supported_suffixes: set[str],
+ output_arg: str | None,
+ convert_one: ConvertOne,
+) -> int:
+ """Run one converter across explicit files and non-recursive directories."""
+ expanded, expansion_errors, saw_directory = expand_directory_inputs(
+ inputs,
+ lambda path: path.suffix.lower() in supported_suffixes,
+ )
+ sources = [Path(item) for item in expanded]
+ batch_mode = saw_directory or len(sources) > 1
+
+ if output_arg and batch_mode:
+ output_dir = Path(output_arg)
+ if output_dir.exists() and not output_dir.is_dir():
+ _print_status(f"[ERROR] Batch output path is not a directory: {output_arg}")
+ return 1
+ output_dir.mkdir(parents=True, exist_ok=True)
+
+ success_count = 0
+ failed: list[str] = []
+ skipped: list[str] = list(expansion_errors)
+ used_outputs: set[Path] = set()
+
+ for source in sources:
+ output = _output_for(source, output_arg, batch_mode, used_outputs)
+ if batch_mode:
+ _print_status(f"\n==> {source}")
+ try:
+ converted = convert_one(source, output)
+ sys.stdout.flush()
+ if converted:
+ success_count += 1
+ else:
+ failed.append(str(source))
+ except Exception as exc:
+ sys.stdout.flush()
+ failed.append(f"{source}: {exc}")
+ _print_status(f"[ERROR] {source}: {exc}")
+
+ if batch_mode:
+ sys.stdout.flush()
+ _print_status(f"\n[Done] Success: {success_count}/{len(sources)}, Failed: {len(failed)}")
+ if skipped:
+ _print_status("\n[Skipped directories]:")
+ for item in skipped:
+ _print_status(f" - {item}")
+ if failed:
+ _print_status("\n[Failed inputs]:")
+ for item in failed:
+ _print_status(f" - {item}")
+
+ if not sources:
+ return 1
+ return 0 if not failed and not skipped else 1
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 cc691c93..9d2801c3 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
@@ -38,6 +38,7 @@ if str(_SCRIPTS_DIR) not in sys.path:
sys.path.insert(0, str(_SCRIPTS_DIR))
from console_encoding import configure_utf8_stdio # noqa: E402
+from _batch import run_path_batch # noqa: E402
from _conversion_profile import write_conversion_profile_best_effort # noqa: E402
configure_utf8_stdio()
@@ -1448,7 +1449,7 @@ def convert_to_markdown(input_path: str, output_path: str | None = None) -> str:
return markdown
-def main() -> None:
+def main() -> int:
parser = argparse.ArgumentParser(
description="Convert documents to Markdown "
"(pure-Python for common formats, pandoc fallback for the rest)",
@@ -1456,6 +1457,8 @@ def main() -> None:
epilog="""
Examples:
python doc_to_md.py lecture.docx # Word → Markdown (mammoth)
+ python doc_to_md.py lecture.docx notes.html # Convert multiple files
+ python doc_to_md.py ./docs -o ./markdown # Convert supported files in a directory
python doc_to_md.py article.html # HTML → Markdown (markdownify)
python doc_to_md.py book.epub # EPUB → Markdown (ebooklib)
python doc_to_md.py notebook.ipynb # Jupyter → Markdown (nbconvert)
@@ -1468,13 +1471,22 @@ Pandoc fallback formats (require system pandoc):
.doc .odt .rtf .tex/.latex .rst .org .typ
""",
)
- parser.add_argument("input", help="Input document file")
- parser.add_argument("-o", "--output", help="Output Markdown file path")
+ parser.add_argument("inputs", nargs="+", help="Input document file(s) or directories")
+ parser.add_argument(
+ "-o",
+ "--output",
+ help="Output Markdown file for one input, or output directory for multiple inputs/directories",
+ )
args = parser.parse_args()
- result = convert_to_markdown(args.input, args.output)
- sys.exit(0 if result else 1)
+ supported_suffixes = set(NATIVE_FORMATS) | set(PANDOC_FORMATS)
+ return run_path_batch(
+ args.inputs,
+ supported_suffixes,
+ args.output,
+ lambda source, output: bool(convert_to_markdown(str(source), str(output))),
+ )
if __name__ == "__main__":
- main()
+ raise SystemExit(main())
diff --git a/skills/ppt-master/scripts/source_to_md/excel_to_md.py b/skills/ppt-master/scripts/source_to_md/excel_to_md.py
index b14692b1..54506a1f 100644
--- a/skills/ppt-master/scripts/source_to_md/excel_to_md.py
+++ b/skills/ppt-master/scripts/source_to_md/excel_to_md.py
@@ -25,6 +25,7 @@ if str(_SCRIPTS_DIR) not in sys.path:
sys.path.insert(0, str(_SCRIPTS_DIR))
from console_encoding import configure_utf8_stdio # noqa: E402
+from _batch import run_path_batch # noqa: E402
from _conversion_profile import write_conversion_profile_best_effort # noqa: E402
configure_utf8_stdio()
@@ -351,13 +352,15 @@ def convert_to_markdown(
return markdown
-def main() -> None:
+def main() -> int:
parser = argparse.ArgumentParser(
description="Convert Excel workbooks to Markdown",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
Examples:
python excel_to_md.py report.xlsx
+ python excel_to_md.py report.xlsx budget.xlsm
+ python excel_to_md.py ./workbooks -o ./markdown
python excel_to_md.py report.xlsx -o output.md
python excel_to_md.py report.xlsm --max-rows 200 --max-cols 40
@@ -368,8 +371,12 @@ Unsupported by default:
.xls Resave as .xlsx first
""",
)
- parser.add_argument("input", help="Input Excel workbook")
- parser.add_argument("-o", "--output", help="Output Markdown file path")
+ parser.add_argument("inputs", nargs="+", help="Input Excel workbook(s) or directories")
+ parser.add_argument(
+ "-o",
+ "--output",
+ help="Output Markdown file for one input, or output directory for multiple inputs/directories",
+ )
parser.add_argument(
"--max-rows",
type=int,
@@ -384,14 +391,20 @@ Unsupported by default:
)
args = parser.parse_args()
- result = convert_to_markdown(
- args.input,
+ return run_path_batch(
+ args.inputs,
+ EXCEL_FORMATS | LEGACY_EXCEL_FORMATS,
args.output,
- max_rows=args.max_rows,
- max_cols=args.max_cols,
+ lambda source, output: bool(
+ convert_to_markdown(
+ str(source),
+ str(output),
+ max_rows=args.max_rows,
+ max_cols=args.max_cols,
+ )
+ ),
)
- sys.exit(0 if result else 1)
if __name__ == "__main__":
- main()
+ raise SystemExit(main())
diff --git a/skills/ppt-master/scripts/source_to_md/pdf_to_md.py b/skills/ppt-master/scripts/source_to_md/pdf_to_md.py
index d4081912..22460d7e 100644
--- a/skills/ppt-master/scripts/source_to_md/pdf_to_md.py
+++ b/skills/ppt-master/scripts/source_to_md/pdf_to_md.py
@@ -19,6 +19,7 @@ if str(_SCRIPTS_DIR) not in sys.path:
sys.path.insert(0, str(_SCRIPTS_DIR))
from console_encoding import configure_utf8_stdio # noqa: E402
+from _batch import run_path_batch # noqa: E402
from _conversion_profile import write_conversion_profile_best_effort # noqa: E402
configure_utf8_stdio()
@@ -1082,6 +1083,8 @@ def main() -> int:
epilog='''
Examples:
python pdf_to_md.py book.pdf # Convert a single file
+ python pdf_to_md.py book.pdf appendix.pdf # Convert multiple files
+ python pdf_to_md.py ./pdfs -o ./markdown # Convert PDFs in a directory
python pdf_to_md.py book.pdf -o output.md # Specify output file
python pdf_to_md.py book.pdf --render-vector-figures
@@ -1095,8 +1098,12 @@ Structure detection features:
'''
)
- parser.add_argument('input', help='PDF file')
- parser.add_argument('-o', '--output', help='Output Markdown file')
+ parser.add_argument('inputs', nargs='+', help='PDF file(s) or directories')
+ parser.add_argument(
+ '-o',
+ '--output',
+ help='Output Markdown file for one input, or output directory for multiple inputs/directories',
+ )
parser.add_argument(
'--images',
choices=['all', 'filtered', 'none'],
@@ -1117,22 +1124,21 @@ Structure detection features:
args = parser.parse_args()
- input_path = Path(args.input)
-
- if not input_path.is_file():
- print(f"Error: PDF file not found: {args.input}")
- return 1
-
- output = args.output or str(input_path.with_suffix('.md'))
- extract_pdf_to_markdown(
- str(input_path),
- output,
- images=args.images,
- render_vector_figures=args.render_vector_figures,
- vector_figure_dpi=args.vector_figure_dpi,
+ return run_path_batch(
+ args.inputs,
+ {'.pdf'},
+ args.output,
+ lambda source, output: bool(
+ extract_pdf_to_markdown(
+ str(source),
+ str(output),
+ images=args.images,
+ render_vector_figures=args.render_vector_figures,
+ vector_figure_dpi=args.vector_figure_dpi,
+ )
+ ),
)
- return 0
if __name__ == '__main__':
- exit(main())
+ raise SystemExit(main())
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.py
index 6bd79116..c6774d6a 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
@@ -39,6 +39,7 @@ if str(_SCRIPTS_DIR) not in sys.path:
sys.path.insert(0, str(_SCRIPTS_DIR))
from console_encoding import configure_utf8_stdio # noqa: E402
+from _batch import run_path_batch # noqa: E402
from _conversion_profile import write_conversion_profile_best_effort # noqa: E402
from pptx import Presentation
@@ -842,7 +843,7 @@ def convert_presentation_to_markdown(
return markdown_content
-def main() -> None:
+def main() -> int:
"""Run the CLI entry point."""
parser = argparse.ArgumentParser(
description="Convert PowerPoint files to Markdown",
@@ -850,6 +851,8 @@ def main() -> None:
epilog="""
Examples:
python ppt_to_md.py slides.pptx
+ python ppt_to_md.py slides.pptx appendix.pptx
+ python ppt_to_md.py ./decks -o ./markdown
python ppt_to_md.py slides.pptx -o output.md
python ppt_to_md.py deck.ppsx -o notes/deck.md
@@ -859,20 +862,22 @@ Supported formats:
Legacy .ppt is not parsed directly. Resave it as .pptx or export it to PDF first.
""",
)
- parser.add_argument("input", help="Input PowerPoint file")
- parser.add_argument("-o", "--output", help="Output Markdown file")
+ parser.add_argument("inputs", nargs="+", help="Input PowerPoint file(s) or directories")
+ parser.add_argument(
+ "-o",
+ "--output",
+ help="Output Markdown file for one input, or output directory for multiple inputs/directories",
+ )
args = parser.parse_args()
- input_path = Path(args.input)
-
- if not input_path.is_file():
- print(f"Error: PowerPoint file not found: {args.input}")
- sys.exit(1)
- 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)
+ return run_path_batch(
+ args.inputs,
+ set(SUPPORTED_FORMATS),
+ args.output,
+ lambda source, output: bool(convert_presentation_to_markdown(str(source), str(output))),
+ )
if __name__ == "__main__":
- main()
+ raise SystemExit(main())
diff --git a/skills/ppt-master/scripts/source_to_md/web_to_md.py b/skills/ppt-master/scripts/source_to_md/web_to_md.py
index 1c550a78..4dfbe9ef 100644
--- a/skills/ppt-master/scripts/source_to_md/web_to_md.py
+++ b/skills/ppt-master/scripts/source_to_md/web_to_md.py
@@ -43,7 +43,10 @@ if str(_SCRIPTS_DIR) not in sys.path:
sys.path.insert(0, str(_SCRIPTS_DIR))
from console_encoding import configure_utf8_stdio # noqa: E402
-from _conversion_profile import write_conversion_profile_best_effort # noqa: E402
+from _conversion_profile import ( # noqa: E402
+ profile_path_for,
+ write_conversion_profile_best_effort,
+)
configure_utf8_stdio()
@@ -805,8 +808,13 @@ def simple_html_to_markdown_traversal(soup: Tag | BeautifulSoup | None) -> str:
return md or ""
-def process_url(url: str, output_file: str | None = None) -> tuple[bool, str, str | None]:
- """Fetch, convert, and save one web page as Markdown."""
+def process_url(url: str, output_file: str | None = None) -> tuple[bool, str, str | None, str | None]:
+ """Fetch, convert, and save one web page as Markdown.
+
+ Returns (success, url, error, output_path). output_path is the actual saved
+ Markdown path (derived from the article title when no output_file is given),
+ so a caller can locate a title-named file it did not choose upfront.
+ """
print(f"\n[Fetching] {url}")
try:
html = fetch_url(url)
@@ -881,11 +889,27 @@ def process_url(url: str, output_file: str | None = None) -> tuple[bool, str, st
print(f" [OK] Saved: {output_path}")
if profile_path:
print(f" [OK] Conversion profile: {profile_path}")
- return True, url, None
+ return True, url, None, output_path
except Exception as e:
print(f" [ERROR] {str(e)}")
- return False, url, str(e)
+ return False, url, str(e), None
+
+
+def _write_emit_result(result_file: str, url: str, markdown_path: str) -> None:
+ """Write the actual saved path as JSON so a caller can locate the output."""
+ md = Path(markdown_path).resolve()
+ profile = profile_path_for(md)
+ payload = {
+ "input": url,
+ "markdown": str(md),
+ "conversion_profile": str(profile) if profile.is_file() else "",
+ }
+ try:
+ Path(result_file).write_text(
+ json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+ except OSError as exc:
+ print(f" [WARN] Could not write --emit-result: {exc}")
def main() -> None:
@@ -897,6 +921,10 @@ def main() -> None:
"-f", "--file", help="File containing URLs (one per line)")
parser.add_argument("-o", "--output", help="Output file (single URL only)")
parser.add_argument("-d", "--dir", help="Output directory")
+ parser.add_argument(
+ "--emit-result",
+ help="On success, write the saved output path as JSON to this file "
+ "(single-URL dispatcher use, so a title-named file can be located)")
args = parser.parse_args()
@@ -924,8 +952,10 @@ def main() -> None:
for i, url in enumerate(targets):
# Allow specific output file only if 1 URL
out = args.output if (len(targets) == 1 and args.output) else None
- success, url, err = process_url(url, out)
+ success, url, err, out_path = process_url(url, out)
results.append((success, url, err))
+ if args.emit_result and success and out_path:
+ _write_emit_result(args.emit_result, url, out_path)
# Summary
success_count = sum(1 for r in results if r[0])