DOCSEARCHbyAlgolia
Submit Docs

md2pptx

repository·main·Indexed 19 days ago

https://github.com/martinpacker/md2pptx

A Markdown to PowerPoint converter that generates .pptx and .pptm slide decks from structured Markdown files. It supports various slide types including title, section, bullet, table, and media slides, as well as two-column layouts via contentsplit. Requires Python 3.10 or later (as of April 1, 2025) and the python-pptx dependency.

Tokens
24.8K
Snippets
107
Records
130
Agent score
66%

What's inside md2pptx

  1. What is md2pptx?

    main
    md2pptx is a Markdown preprocessor that converts Markdown text into a PowerPoint presentation. It supports generating both standard .pptx files and .pptm files (which can invoke VBA macros). It is designed to automate the creation of presentations from structured text.

  2. md2pptx Directory Structure

    main

    Understanding the project layout for locating assets:

    • root/: Contains Python code and Martin Template.pptx (the default starter template).
    • applescript/: Contains shipped AppleScript scripts (e.g., copyPresentation.applescript).
    • media/: Contains icons and other media assets.
    • docs/: Contains documentation files.
    • examples/: Contains usage examples.
    • Drafts Actions/: Contains Drafts actions.

  3. Create Table of Contents and Section slides

    main

    You can generate a Table of Contents (TOC) slide by creating a bulleted list slide where each top-level bullet is an internal link to a section.

    Requirements:

    1. The slide title must be "Topics" (or a custom title defined by tocTitle).
    2. Section slides must have unique titles that match the bullet text in the TOC slide.
    3. Only one slide should have the TOC title.

    TOC Styles (tocStyle)

    • chevron: Creates a chevron-style TOC. Section slides will highlight the current section by removing its background.
    • circle: Creates a circle-style TOC. Section slides will highlight the current section by removing the background and emphasizing the circle.
    • plain: Creates a list of live links. Unlike the other styles, plain does not affect the appearance of Section slides.

    TOC Customization

    • tocTitle: Set this if your TOC slide title is something other than "Topics" (e.g., tocTitle: Agenda).
    • tocLinks: Set to yes to enable live links in the PowerPoint slideshow for chevron and circle styles.
    • tocItemHeight: Sets the height of TOC items in inches (Default: 1.0 for chevron, 1.25 for circle).
    • tocRowGap: Sets the vertical gap between rows in inches (Default: 0.75).
    • tocFontSize: Sets the font size of TOC entries in points.
    • tocItemColour: Sets the background color of TOC items using a hexadecimal RGB value (e.g., E0E0FF). This is useful when tocLinks: yes makes text hard to read.
    ### Topics

* [A Section](#a-section)
    * [Another Section](#another-section)
    tocStyle: chevron
tocTitle: Agenda
tocLinks: yes
tocItemColour: E0E0FF

  4. Create slides with multiple content blocks

    main

    Since version 2.0, slides can contain multiple content blocks (up to 10).

    Supported Blocks:

    • One list block (with optional cards).
    • Multiple code blocks.
    • Multiple tables.
    • Multiple graphics (multiple graphics side-by-side count as a single block).

    Layout Logic:

    • The order of blocks in your Markdown determines their position.
    • Vertical Layout (Default): Blocks appear one above the other.
    • Horizontal Layout: Blocks appear side-by-side (e.g., a list to the left of a graphic).
    • You can control the split direction (horizontal vs vertical) and the proportion of space each block occupies using metadata.
    ### Here Is A title

* Here is a bullet
      * Here is a sub-bullet

![](my-graphic.png)

  5. Annotate slides with lines, shapes, and images

    main

    Use the annotation helper routines to add visual elements to a slide. Supported types include:

    • Lines: Can include arrowheads.
    • Rectangles: Can have rounded corners and text.
    • Ovals: Can include text.
    • Images

    Key Configuration Rules:

    • Dimensions: All dimensions (except line widths) are in inches and can be negative.
    • Positioning: Positions are relative to the top-left of the slide.
    • Styling:
      • Foreground and background colors can be set.
      • Border line widths are specified in points.
      • Line styles: Use "-" for a single line and "=" for a double line.
    • Data Format: Annotations are passed as a list of values to RunPython.doAnnotations or as lines in a CSV for RunPython.annotationsFromCSV.

  6. Specify colors using Theme Colors or RGB

    main

    When defining colors in metadata, you can use either PowerPoint Theme Colors or hexadecimal RGB values.

    Theme Colors

    Use standard PowerPoint theme names. These are case-insensitive. Available names:

    • NONE, ACCENT 1 through ACCENT 6
    • BACKGROUND 1 through BACKGROUND 2
    • DARK 1 through DARK 2
    • LIGHT 1 through LIGHT 2
    • TEXT 1 through TEXT 2
    • HYPERLINK, FOLLOWED HYPERLINK
    • MIXED

    RGB Colors

    Use 6-digit hexadecimal values. You must include the octothorpe (#) prefix.

    Example: ItalicColour: #FF0000

    BoldColour: ACCENT 1
ItalicColour: #FF0000

  7. Use HTML span classes for text styling

    main

    You can associate CSS-like classes with specific text effects using HTML <span> elements. These classes are defined in your metadata using the style. prefix.

    Available Style Metadata Keys

    • style.bgcolor.[classname]: [color]: Sets the background color of the text span. Use RGB (e.g., FFFF00) or Theme Colors.
    • style.fgcolor.[classname]: [color]: Sets the foreground (text) color.
    • style.emphasis.[classname]: [effects]: Applies emphasis. Effects are space-separated: bold, italic, underline.
    • style.fontsize.[classname]: [size]: Sets font size in pixels (e.g., 40px).
    • style.cellcolor.[classname]: [color]: Sets the background color of a table cell. The first matching span class in the cell is used.
    • style.cellbox.[classname]: (Referenced for table cell border color).
    <!-- Metadata Definition -->
style.bgcolor.yellow: FFFF00
style.emphasis.important: bold underline
style.fontsize.large: 40px

<!-- Markdown Usage -->
This is <span class="yellow">highlighted</span>.
This is <span class="important">very important</span>.
This is <span class="large">big text</span>.

  8. Python version compatibility requirements

    main

    md2pptx requires Python 3. The minimum version requirement changes periodically to leverage new language features and maintain support for official Python releases:

    • Current (since April 1, 2025): Python 3.10 or later.
    • Expected (from April 1, 2026): Python 3.11 or later.
    • Expected (from April 1, 2027): Python 3.12 or later.

    python-pptx specifically requires Python 3.8 or later due to the use of the Walrus Operator.

  9. Use Dynamic Metadata to alter settings mid-presentation

    main

    You can change settings (like visibility, table styles, or card layouts) for a specific slide and all subsequent slides by using HTML comments immediately following a heading.

    Syntax: <!-- md2pptx: <key>: <value> -->

    Special Values:

    • pres: Revert to the presentation's global value.
    • default: Revert to the md2pptx default.
    • prev or pop: Revert to the previous value (destructive/pops the stack).
    • Any other value: Used literally.

  10. Arrange multiple graphics using table special cases

    main

    While you cannot embed images inside cells for standard tables, md2pptx provides 'special case' layouts where using a table structure triggers a specific graphic grid layout instead of a standard table.

    Supported Layouts

    • Two Graphics Side-by-Side: A single row table with two cells.
    • Two-by-Two Grid: A two-row table with two cells per row.
    • Three Graphics (T-shape): A two-row table where the first row has two graphics and the second row has one centered graphic.
    • Three Graphics (Inverted T): A two-row table where the first row has one graphic and the second row has two.
    • One Graphic Above Another: A two-row table with one cell per row.

    Implementation Rules

    • Do not include headings within these specific table structures.
    • For the 2x2 or 3-graphic layouts, do not exceed two rows.
    • The vertical bars | are optional in these cases as regular Markdown processors might render them literally.
    • You can force alignment for a single graphic in a row by using empty cells (e.g., |![](img.png)|| aligns the image to the left).
    |![](top-left-graphic.png)|![](top-right-graphic.png)|
|![](bottom-left-graphic.png)|![](bottom-right-graphic.png)|

  11. Variables available in md2pptx Python blocks

    main

    When running Python code via run-python, md2pptx provides several pre-defined variables that you can use to interact with the presentation and the current slide:

    • prs: The python-pptx Presentation object being created.
    • slide: The current python-pptx Slide object you are manipulating.
    • renderingRectangle: An object defining the dimensions and position of the area allocated for your Python drawing/rendering.

  12. How slide notes are parsed and structured

    main

    When using md2pptx, slide notes follow specific parsing rules that differ from standard Markdown processors:

    1. No Structured Lists: You cannot use structured items like bulleted lists within slide notes. The parser does not support them.
    2. Note Aggregation: You can intersperse notes with slide content (e.g., placing note paragraphs between code blocks). However, md2pptx does not maintain the interleaved order. Instead, it gathers all note content found on a slide and aggregates them into a single block in the slide notes section. This means the notes will not intersperse with the slide content in the final PowerPoint output as they appear in your Markdown source.