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

docs(source-to-md): clarify default beside-source output and import-sources usage

hugohe3f91a54225e15
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index a1e476ae..8fda3bf7 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -142,9 +142,10 @@ routes by source type, and writes the standard Markdown plus conversion profile.
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. 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
+Use `source_to_md.py -t <type>` only when extension detection is ambiguous.
+Default local conversion writes Markdown/profile outputs beside each source file.
+Use `-o` only when a specific output file/directory is required; with multiple
+inputs or directory inputs, `-o` is an output directory. Backend converter details are documented in
[`scripts/docs/conversion.md`](scripts/docs/conversion.md).
> **Office vector assets (EMF/WMF) from DOCX/PPTX sources**:
@@ -192,7 +193,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`. 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.
+> ⚠️ **MUST use `--move`** (not copy): all source files — Step 1's generated Markdown, original PDFs / MDs / images — go into `sources/` via `import-sources --move`. If Step 1 wrote Markdown beside the original sources, pass that source path/directory once. If Step 1 used `-o` to write Markdown elsewhere, pass both the original source path(s)/directory and the 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/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index a8996cfb..cf193d8e 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -14,7 +14,7 @@ now also write a lightweight sidecar profile when conversion succeeds:
| Output | Convention |
|---|---|
-| Markdown | `<stem>.md` unless `-o` selects another path |
+| Markdown | `<stem>.md` beside the local source unless `-o` selects another path |
| Asset directory | `<stem>_files/` when the backend extracts images or media |
| Image manifest | `<stem>_files/image_manifest.json` when image metadata is available |
| Conversion profile | `<stem>.conversion_profile.json` beside the Markdown output |
@@ -36,10 +36,11 @@ 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 ./sources
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
+python3 scripts/source_to_md.py ./sources -o ./markdown # explicit separate output directory
python3 scripts/source_to_md.py workbook.xlsx --json
python3 scripts/source_to_md.py deck.pptx
python3 scripts/source_to_md.py https://example.com/article -o article.md
@@ -59,8 +60,10 @@ Useful options:
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` and the backend converters support
-single files, explicit multi-file inputs, and non-recursive directory inputs.
+all source paths / URLs. For local files, the default is to keep generated
+Markdown/profile outputs beside the original source. `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`
@@ -70,7 +73,8 @@ Recommended first choice for native PDFs.
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
+python3 scripts/source_to_md/pdf_to_md.py ./pdfs
+python3 scripts/source_to_md/pdf_to_md.py ./pdfs -o ./markdown # explicit separate output directory
# Image extraction control (default: filtered)
python3 scripts/source_to_md/pdf_to_md.py book.pdf --images filtered # size/quality filters applied
@@ -111,7 +115,8 @@ Pandoc fallback (only if you need these):
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 ./docs
+python3 scripts/source_to_md/doc_to_md.py ./docs -o ./markdown # explicit separate output directory
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
```
@@ -146,7 +151,8 @@ Unsupported by default:
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 ./workbooks
+python3 scripts/source_to_md/excel_to_md.py ./workbooks -o ./markdown # explicit separate output directory
python3 scripts/source_to_md/excel_to_md.py report.xlsm --max-rows 200 --max-cols 40
```
@@ -179,7 +185,8 @@ Supported formats include:
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 ./decks
+python3 scripts/source_to_md/ppt_to_md.py ./decks -o ./markdown # explicit separate output directory
python3 scripts/source_to_md/ppt_to_md.py template.ppsx -o notes/template.md
```
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index 97630686..a461d56a 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -19,8 +19,9 @@ 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/`.
+ pass the source file/directory once when generated Markdown lives beside the
+ original source. If Step 1 used `-o` to write Markdown elsewhere, pass both
+ the original source path/directory and the Markdown output path/directory.
- 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.