pptgen-drawio

PPT multi-page Draw.io generation (thesis defense + general report)

This skill supports two modes,shared ppt_template/、scripts/、reference/ directory, as well as Step 0 custom template、Step 1 determine content and style、Step 3 & 4 output and export full workflow.

Mode identification

Mode	When to use	Content source	Default page order	Output file
Thesis defense	Degree thesis defense, proposal, pre-defense	paper-write structured extraction	Cover→Table of contents→Background→Current status→Methods→Innovations→Experiments→Conclusion→Acknowledgments→Q&A	`paper-defense.drawio`
General report	Work report, product introduction, speech	Extract/generate from user message	Cover→Table of contents→Section title→Content pages→Summary→Acknowledgments→Q&A	`general-presentation.drawio`

Step 0: User custom template (optional, shared by both modes)

If the user provides their own .pptx template file:

Template placement: Place the .pptx into the ppt_template/ directory

Run style extraction: Execute in the skill root directory:

python scripts/analyze_pptx.py ppt_template/xxx.pptx reference/style-custom.md

Read reference/style-custom.md as the "custom style" and continue

Directory conventions：ppt_template/ stores templates,scripts/analyze_pptx.py style extraction,reference/ style files

Step 1: Determine content and style (shared by both modes)

1.1 Determine content

Thesis defense: If the user only has the full paper: first call paper-write's "structured information extraction"; if structured information is already provided: extract [thesis title] [discipline direction] [defense duration] [thesis structure/table of contents] [core content of each chapter] [innovations/contributions] etc. from the message, and ask if anything is missing
General report: Extract the slide outline and content from the user message, or expand it into a complete structure based on the core requirements

1.2 Choose style

Both modes can choose one of the following styles,read the corresponding reference fileto obtain color schemes, fonts, layout rules, and XML style snippets:

#	Style	Primary color	Accent color	Top bar decoration present or not	reference file
1	Classic academic / business rigorous	`#1B2A4A`	`#C9A84C`	Yes: top bar 150px + gold line 8px	`reference/style1-classic-academic.md`
2	Modern minimalist / large typography feel	`#231F20`	`#F5C638`	None, relying on whitespace and font size differences	`reference/style2-minimal-bigtype.md`
3	Warm academic / approachable	`#2C5160`	`#B7472A`	Yes, same structure as style one	`reference/style3-warm-academic.md`
4	Tech bright / modern cutting-edge	`#0170C1`	Same as primary color	Yes	`reference/style4-tech-modern.md`
5	Custom	Extract from style-custom.md		See template	`reference/style-custom.md`

Thesis defense：Default style 1 when the user does not specify
General report：User-selected or automatically recommended based on context
Styles 1 / 3 / 4 are the same layout with different color schemes (top bar + thin lines + footer),only style 2 is a truly different layout. When the user wants it to "look different," recommend style 2; for traditional engineering college defenses, recommend style 1

Step 2: Generate multi-page Draw.io XML

You must first read the reference file of the selected style, and generate XML based on that style.

Canvas: 16:9 (pageWidth=1920, pageHeight=1080)
Page order: use the default page order in the pattern recognition table
Page count:determined by the defense duration obtained in Step 1.1, see 2.1 below

2.1 Thesis defense mode page order (converted by duration)

The page count is the sum of three parts:

封面 · 目录 · 已有成果 · 致谢/Q&A            → 4 页，任何时长都有
每章一个节标题过渡页                          → 章数 × 1 页
各章内容页                                    → 按下表分配

choose a column by duration, the numbers in the table are "content pages per chapter":

Chapter	10 minutes	15 minutes	20 minutes
01 Research background and significance	1	2	3
02 Domestic and international research status	1	1	2
03 Method (including innovations)	2	3	3
04 Experimental results	1	2	2
05 System design and implementation	1	1	2
06 Summary and outlook	1	1	1
Content pages subtotal	7	10	13
Total pages(+4 fixed +6 section titles)	17	20	23

If the duration is not in the table, use 45 seconds per pageto estimate: total pages ≈ duration (minutes) × 60 ÷ 45, then distribute to each chapter according to the proportions in the table above.

The proportion of the method chapter is a hard requirement: Method + experiments combined must be no less than 40% of the content pages. This is the part defense committee members actually listen to; if the background and current status are discussed at length, you will be interrupted.

If the user specifies a number of pages, follow the user's, and the table above is only used when the user does not specify a page count.

The previous fixed 23-page wording is deprecated—that number comes from style1 's source file 答辩PPT.pptx, which is the actual page count of a defense of more than 20 minutes and is not applicable to 10–15 minutes.

Each reference/styleX-*.md only definesstyles and layouts(colors, fonts, component layouts), and does not define page order or page count.

2.2 File naming and delivery (recommended, Windows-compatible)

Recommended naming (generation/export stage): Prefer ASCII file names (English letters/numbers/hyphens) to reduce issues such as garbled Chinese file names and commands failing to find files in PowerShell/encoding environments.
- Recommended:defense-style4-tech.drawio、defense-style4-tech.pptx
- If a Chinese name is required: it is recommended to first complete the export with an ASCII name, then rename it to Chinese in File Explorer
Delivery order (recommended process): First provide .drawio(source file) → run the command to export .pptx(delivery file) → verify the page count
Delivery dependencies: The recipient only needs to open .pptx(attach if necessary .drawio), and does not need to install Python; scripts/code are only used on the generation side to automatically write XML (optional).

⚠️ Known pitfalls checklist (go through each item before generation)

✅ Must-pass checklist (7 items)

Multi-page structure: The root node must be <mxfile>, and one <diagram>per page (otherwise the export will become 1 page).
Coordinate system per page: within each <diagram> , x starts from 0; background rectangle x=0,y=0,w=1920,h=1080; every page has mxCell id="0" and mxCell id="1" parent="0"。
ID uniqueness: all mxCell id within the entire file must be unique; each <diagram id="..."> must also be unique.
Write in one go：.drawio must be written completely in one go (do not overwrite/concatenate the XML multiple times).
Use 
for line breaks, do not use real newline characters. The XML specification states that literal newlines in attribute values are normalized to spaces, so value="第一行\n第二行" after export isone line, with multiple spaces in between. Measured (drawio2pptx 0.0.7 + PowerPoint):

Writing Export result

value="A
B" ✅ two lines

value="A<br>B" ✅ two lines (split into two paragraphs)

value="A real newline B" ❌ one line, newline becomes space

Use 
for multi-line body text; use <br>when it needs to be split into separate paragraphs (e.g., each list item as its own paragraph). Text style must contain whiteSpace=wrap;html=1;。
Do not mistakenly replace white text: keep top bar/dark block text as fontColor=#FFFFFF; for background color replacement, prioritize changing fillColor, do not globally replace all #FFFFFF。
Occlusion check: decorative blocks with background color must not cross the body text area; do not place background-colored labels between two columns of cards (they will cover the text).

Writing	Export result
`value="A B"`	✅ two lines
`value="A<br>B"`	✅ two lines (split into two paragraphs)
`value="A` real newline `B"`	❌ one line, newline becomes space

There were originally three more rules, "cell count per page ≥ N", "height budgeted at 1.4 times the font size", and "page count validation"—the first two were guessing at the rendering result, and the third could only validate the page count. All have been replaced by the render_check.py from Step 5: that script uses real font files to measure width and directly tells you which frame on which page will clip text.Do not rely on adding cells to pad the count or estimating line height by a multiplier.

Minimal usable multi-page template (structure only for illustration)

<mxfile host="app.diagrams.net">
  <diagram id="p1" name="封面">
    <mxGraphModel page="1" pageWidth="1920" pageHeight="1080">
      <root>
        <mxCell id="0"/><mxCell id="1" parent="0"/>
      </root>
    </mxGraphModel>
  </diagram>
  <diagram id="p2" name="目录">
    <mxGraphModel page="1" pageWidth="1920" pageHeight="1080">
      <root>
        <mxCell id="0"/><mxCell id="1" parent="0"/>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Step 3 & 4 & 4.5 & 5: Output Draw.io, export PPT, patch, verify rendering (shared by both modes)

Step 3: Output the Draw.io file

Write the generated XML in one go to the workspace .drawio file (use paper-defense.drawiofor thesis defenses, use general-presentation.drawiofor general presentations), and briefly describe the summary of each page.

The writing method must satisfy checklist item 4 "write in one go" and item 5 "use 
for line breaks".

Step 4: Export PPT (required)

If not installed:pip install drawio2pptx -q

First switch to the directory containing .drawio directory, otherwise the file cannot be found:

cd /d/你的项目目录          # bash / zsh
drawio2pptx paper-defense.drawio paper-defense.pptx

Set-Location "D:\你的项目目录"   # PowerShell
drawio2pptx paper-defense.drawio paper-defense.pptx

The output should contain Saved xxx.pptx (N slides)，N equal to the <diagram> count.Matching the page count only means no pages were lost, not that the layout is correct, continue to Step 4.5.

Step 4.5: Patch the pptx (required, especially do not skip for Chinese PPTs)

python scripts/postprocess_pptx.py paper-defense.pptx

Why it must be run: drawio2pptx 0.0.7's io/drawio_loader.py has a "nowrap heuristic"—when all paragraphs in a text box contain no whitespace characters, it will whiteSpace=wrap overwritten to wrap="none"。Chinese sentences have no spaces, so every purely Chinese text box is judged as nowrap, and the text flows endlessly to the right along one line, breaking through the right column and running off the canvas.

When the font size is small, one line just fits and you can't tell; but once you lay it out according to the 40 pt rule above, it all collapses. This script forces all text boxes' word_wrap back to True。

Note the order：render_check.py 's scan is counted as "wraps", so you must patch first and then scan, otherwise the scan result and the actual rendering are not the same thing.

In thesis defense mode, after finishing writing the Step 6 script, run the version with the script again to write the script into the notes area:

python scripts/postprocess_pptx.py paper-defense.pptx --notes paper-defense-script.md

Step 5: Verify rendering (must be executed)

python scripts/render_check.py paper-defense.pptx

The script does two things:

Measure text overflow — use the actual local font files to measure the pixel width of each line, calculate how tall the text box needs to be, and compare it with the box height. If there is ❌ OVERFLOW then go back to Step 2 to change that page's box height or reduce text, rerun after changing, until only ⚠️ TIGHT or all clear remains. A non-zero exit code indicates overflow.
Export PNG page by page — On Windows use PowerPoint COM, on other platforms use LibreOffice + pdftoppm。After exporting, you must actually look at the images page by page, and prioritize checking whether text runs out of the box and whether decorative blocks cover the text. When neither engine is available, only the scan result is produced; at this point you must tell the user "no visual verification was done".

If the font is not installed, the script will prompt "the measured width is only an estimate" — in this case the scan result can only be used as a reference, and you must look at the images.

Step 6: Output the script (required in thesis defense mode)

A defense is spoken. At the same time, write a paper-defense-script.md：

## 第 N 页 · <页面标题>       ⏱ 约 XX 秒
<这一页要说的话，口语，能照着念>

Convert to seconds at 200 characters per minute, and finally check that the difference between the total duration and the defense duration given by the user is within ±1 minute. If the difference is too large, go back to Step 2 to adjust the number of pages
Cover 15 seconds, table of contents 20 seconds, section title pages about 5 seconds, and the remaining time is allocated to content pages
Draw.io does not have the concept of notes, so the script is an independent .md. After writing, return to Step 4.5 and use --notes to write it into the pptx notes area: python scripts/postprocess_pptx.py xxx.pptx --notes xxx-script.md

Export failure troubleshooting (high frequency)

Permission denied / access denied: The target .pptx is being occupied by PowerPoint.
- Solution: export to a new file name (such as *-v2.pptx), or close PPT first and then overwrite-export.
Chinese file name garbled/file not found: Terminal encoding causes abnormal path parsing.
- Solution: switch to ASCII file names for generation and export (see 2.2).
pip install reports SSLError / version not found: Network problem.
- Solution: switch to a mirror pip install drawio2pptx -i https://pypi.tuna.tsinghua.edu.cn/simple, or download the wheel directly from PyPI and then pip install --no-deps xxx.whl then install separately python-pptx lxml（cairosvg is only needed when there is SVG in the image).

Other precautions

Font size rules (all styles): The canvas is 1920×1080 px, and after export it is 20 inches wide— a standard 16:9 slide is only 13.33 inches.The pt value on the canvas divided by 1.5 is the visual size of a regular PPT.

Purpose	Write on the canvas	Equivalent to a regular PPT
Content page body / list bullet points	40 pt	27 pt
In-page subheading	48 pt	32 pt
Content page top bar title	54 pt	36 pt
Figure title / table title	30 pt	20 pt
Footer / page number / date	24 pt	16 pt

For the large numbers and section names on section title pages, follow the examples in each styleX (numbers 120–140 pt, section names 66–72 pt).

The original wording “body text uniformly 18 pt” wasunits not converted: 18 ÷ 1.5 = 12 pt, which is completely unreadable from the back row at a defense. It has been corrected based on actual measurements.

The cost of 40 pt is that each page must have less text, and this is a hard constraint, not a suggestion:

Text box width How many Chinese characters fit on one line

800 px (two columns) 14

1680 px (full width) 30

Therefore, bullet points in two columns must be written as phrases of ≤14 characters, and full-width sentences ≤30 characters. If it does not fit, delete content or change the layout (for example, change 4 horizontal bar cards to a 2×2 grid),do not cram it in by shrinking the font size. In the generation script, height should be calculated with scripts/textmetrics.py before writing the file, and if it does not fit, raise an error directly.
Font recommendations: For Chinese titles/body text, prioritize Microsoft YaHei or SimSun; for numbers, English, and formulas, use Times New Roman. Each style reference can be fine-tuned on this basis (for example, use Georgia for English titles).
XML tags are properly closed, special characters are escaped (&→&，<→<）
Layout per page: full-canvas background rectangle, title area top bar 150 px, body area kept between y=230..990, sufficient whitespace
Shell differences: The commands in this skill are written for bash. Under PowerShell, cd is replaced with Set-Location、tail -n N is replaced with Select-Object -Last N、head -N is replaced with Select-Object -First N。