Hebrew slide-Markdown → PPTX

Converts a Markdown deck written in the slide-authoring format into a clean, RTL-aware .pptx skeleton. This is the slide counterpart of the hebrew-md-to-docx skill, and the inverse of pptx-to-slide-md (so a deck can round-trip: PPTX → slide-Markdown → PPTX).

Why this skill exists

Pasting slide-Markdown into PowerPoint forces the user to right-align every Hebrew paragraph by hand, and still leaves bugs: punctuation and brackets around English (ו-CTO., [^]) drift to the wrong side, and every Hebrew word is underlined as a spelling mistake because the runs carry no Hebrew language tag. This skill fixes all of that at the OOXML level and lays out one slide per block with the title, body, and speaker notes in the right places.

How to use

The converter is md_to_pptx_he.py (Python 3; needs python-pptx, mistune, and Pillow):

bash
pip install python-pptx mistune Pillow --break-system-packages   # if needed
python md_to_pptx_he.py INPUT.md -o OUTPUT.pptx

Options:

• --template DECK.pptx – build on a template so the output inherits a specific

theme, fonts, and slide layouts (see below). Without it, python-pptx's plain default theme is used.

• --overrides overrides.json – pin the base direction of ambiguous paragraphs

({ "3": "rtl", "12": "ltr" }, keyed by the index printed to stderr).

• --code-font Consolas – monospace font for code spans/blocks. Default

Consolas.

Slide size: without a template the deck is 16:9 widescreen (13.33"×7.5"), and the title/body placeholders are widened to fill it. With --template, the template's own slide size and layouts are kept as-is.

By default, run the converter without --template — it uses python-pptx's plain default theme, since the output is meant to be styled afterwards anyway. Only use --template DECK.pptx if the user explicitly asks for a specific template, theme, fonts, or layouts to be applied.

Input format

The document is a sequence of slide blocks. --- on its own line separates slides; === separates a slide's body from its speaker notes.

markdown
# [Section 1: Section Name (~time)]   <- starts a native PowerPoint section
## [Slide 1: Brief Description]        <- scaffolding label, dropped from the slide

# Slide Title                          <- the real slide title
Body markdown: bullets, numbered lists, tables, **bold**, *italic*, `code`, [links](url).
[presenter instruction]                <- moved to the speaker notes
[image: path/to/pic.png — "alt"]       <- embedded onto the slide
[^]                                    <- a click marker; also moved to notes

===

**Speaker Notes:**
Notes in markdown. Single line breaks are preserved.

---

## [Slide 2: ...]
# Next Slide Title
...

Key rules:

• Section labels # [Section N: Name] start a native PowerPoint section. The

label Section N: is stripped; only the name (everything after the colon, e.g. Section Name (~time)) is used. Every following slide belongs to that section until the next section label.

• Slide labels ## [Slide N: ...] are scaffolding for the author and are

dropped. A lone [Slide N] line (as produced by pptx-to-slide-md) is also recognised as a slide label and dropped, so an extracted deck round-trips.

• Slide title is the first # Heading inside the body. # (untitled) (and

# (Slide N — untitled)) is treated as an empty title.

• Presenter instructions in [brackets] inside the body — animations, demos,

[^] click markers, etc. — are removed from the slide and appended to the speaker notes under a "Presenter instructions:" heading. ([text](url) is a link, not an instruction, and is kept.)

• Images written as [image: path — "alt"] are embedded onto the slide

(path resolved relative to the input .md). The alt text is ignored.

• [hidden slide] markers are dropped (the converter does not re-hide slides).

Direction handling (the RTL core)

Unlike Word, PowerPoint sets text direction per paragraph, and there is no per-run RTL flag. So:

• Each paragraph's base direction is chosen by the majority of strong

directional characters (Hebrew vs Latin), and written as a:pPr/@rtl plus a matching @algn (right for RTL, left for LTR).

• Within a paragraph, text is split into runs by script, and each run is tagged

with a language (a:rPr/@lang = he-IL or en-US). This does two jobs: the spell-checker uses the Hebrew dictionary for Hebrew runs (no more everything-is-a-typo), and PowerPoint resolves bidi per run so neutral punctuation (dash, dot, brackets) around English joins the Hebrew side instead of drifting LTR. Digits stay LTR so numbers like 1920 never reverse.

• Near-even paragraphs are printed to stderr as ambiguous; resolve them with

--overrides keyed by the printed index.

• Tables whose header is Hebrew-dominant get right-to-left column order

(a:tbl @rtl).

What gets converted

| Markdown | PowerPoint | | --- | --- | | # Title (first heading in body) | slide title placeholder | | paragraphs, ##+ headings | body placeholder paragraphs (headings bold) | | - / 1. lists | bulleted / auto-numbered paragraphs with hanging indent | | **bold**, *italic*, ~~strike~~ | run formatting | | code / blocks | monospace runs (LTR) | | text | hyperlinked runs | | tables | a table shape (RTL column order when Hebrew) | | image: ...] | embedded picture | | body brackets], ^] | appended to speaker notes | | speaker notes | notes pane; single line breaks preserved |

Speaker notes

Notes keep the author's line structure: a single newline becomes a real line break (Markdown would otherwise collapse it to a space). Bulleted/numbered notes get a hanging indent so the marker is spaced from the text even though the notes text frame defines no list styles.

Limitations

• The output is a plain, unstyled skeleton (default theme). Styling — colors,

fonts, layouts — is a deliberate later step.

• Table and image positioning is a rough estimate (text height can't be known in

advance), so a slide that mixes a lot of body text with a table/image may need manual repositioning.

• Animations are not created; their description is only recorded in the notes.
• Hidden slides come through visible (the marker is dropped).
• Every content slide uses the "Title and Content" layout; pick other layouts by

hand afterwards.