Skip to content

Latest commit

 

History

History
2607 lines (1620 loc) · 120 KB

user-guide.md

File metadata and controls

2607 lines (1620 loc) · 120 KB

Markdown To Powerpoint User Guide

This document describes the md2pptx Markdown preprocessor, which turns Markdown text into a Powerpoint pptx presentation.

In this document we'll refer to it as "md2pptx", pronounced "em dee to pee pee tee ex".

Table Of Contents

Why md2pptx?

There are advantages in creating presentations using a flat file format. Some of these are:

  • You can use any text editor on any platform to create the file.

  • Other tools can generate the file.

    For example, the author uses iThoughtsX on Mac, with its counterpart (iThoughts) on iOS, to generate presentations from outlines.

  • Text editing tools are far quicker and more flexible that the Powerpoint presentation editor.

  • Versioning and collaboration tools - such as git - are much easier to use with a text file than a Powerpoint presentation file.

  • Other flat file formats can be embedded.

    With md2pptx you can use a simple Task Management format called Taskpaper to embed tasks. md2pptx will extract such tasks and generated a "Tasks" slide at the end of the presentation.

The flat file format that md2pptx uses is Markdown. Using Markdown has further advantages:

  • The same text could be used to start, or even complete, a document of a different kind. Perhaps a long-form document.
  • You can render the material in a web browser. Builds of this very documentation are checked that way.
  • Markdown is easy to write.
  • Markdown is compact; The files are tiny.
  • Markdown is used in popular sites, such as Github.

Every piece of text you use to create a Powerpoint presentation with md2pptx is valid Markdown - with very few exceptions. While it might not render exactly the same way put through another Markdown processor, it is generally equivalent. This is one of the key aims of md2pptx.

One final advantage of the md2pptx approach is you can generate presentations without using PowerPoint itself. Indeed you can create presentations on machines where PowerPoint won't even run. All you need is to be able to run Python 3 and install python-pptx.

A Real World Use Case

The author developed a presentation over 10 years in Powerpoint and OpenOffice and LibreOffice. It became very inconsistent in formatting - fonts, colours, indentations, bullets, etc.. It was a horrible mess.

He took the trouble to convert it to Markdown and regenerated it with a very early version of md2pptx. The presentation looks nice again, with consistent formatting.

It was relatively little trouble to convert to Markdown. In fact it took about an hour to convert the 40 slide presentation. The consistency gain was automatic.

Using md2pptx With mdpre

The author also developed mdpre - and actively maintains it.

mdpre is a preprocessor to create Markdown. It has a number of features that might be of use in creating Markdown, with an especial focus on preparing Markdown for md2pptx. These features include:

  • Including files.
  • Setting (and querying) variables.
  • Conditional processing.
  • Conversion of CSV files to Markdown tables.
  • Creating Table Of Contents slides.
  • Generating a slide with annotated "month view" calendars.

The author has made running mdpre and md2pptx together easier by creating a make file. Here is an example (only tested on Mac OS).

Of\ Names\ And\ Numbers.pptx: Of\ Names\ And\ Numbers.md
    md2pptx Of\ Names\ And\ Numbers.pptx < Of\ Names\ And\ Numbers.md >> Of\ Names\ And\ Numbers.log
    cat Of\ Names\ And\ Numbers.log

Of\ Names\ And\ Numbers.md: Of\ Names\ And\ Numbers.mdp
    mdpre -v < Of\ Names\ And\ Numbers.mdp > Of\ Names\ And\ Numbers.md 2> Of\ Names\ And\ Numbers.log

How Do You Use md2pptx?

You write Markdown in exactly the same way as normal, with some understanding of how Markdown is converted to slides (using the information in Creating Slides).

To use md2pptx you need to download it and install the prerequisites.

Installation

To install md2pptx and its prerequisites

  1. Have Python 3.8 or higher installed.
  2. Install python-pptx using the command pip3 install python-pptx. (You might have to install pip firsst.)
  3. Optionally install CairoSVG - using the command pip3 install cairosvg. (This is for SVG graphics support.)
  4. Install md2pptx by copying a version and unzipping it or using git clone. md2pptx can be found here.

Use

The following instructions are for Unix-like systems. (It's developed and used by the developer on Mac OS but should also have identical syntax on Linux.) Windows users will need a slightly different form, but the principle is the same.

Here is a sample invocation:

md2pptx powerpoint-filename < markdown-filename

An alternative is to have the Markdown be in-stream. md2pptx reads from stdin. You can, of course, use stdin in a pipeline. Indeed the developer uses this to pipe from another program. Alternatively, you can specify both an input file and an output file:

md2pptx markdown-filename powerpoint-filename

If the input file doesn't exist md2pptx will terminate with a message. If the input file is empty the same thing will happen.

If you don't specify an input filename and don't redirect stdin md2pptx will await terminal input. This works but is probably only useful when experimenting with syntax with md2pptx.

Messages are written to stderr.

python-pptx license

While python-pptx is not included in md2pptx it is used by it.

To quote from the python-pptx license statement:

The MIT License (MIT)
Copyright (c) 2013 Steve Canny, https://github.com/scanny

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Change Log

Level Date What
3.0.1 15 April 2022 Improved error handling for embedding graphics, video, and audio from the web. Documented here.
3.0 11 April 2022 Added <video> and <audio> element support, described here. Added some links to the Change Log.
2.6.1 19 March 2022 Added tableHeadingSize and fixed bug with cell spanning more than 2 columns.
2.6 18 March 2022 Support multi-column table cells - complying with the MultiMarkdown spec. Added deleteFirstSlide.
2.5.5 5 March 2022 Make tableMargin, marginBase, and numbersHeight dynamically settable.
2.5.4 3 March 2022 Where possible use Content-Type HTTP header to determine graphics file type when fetched from the web.
2.5.3 1 March 2022 Added exception handling when creating temporary file. Also when retrieving files from a URL.
2.5.2 27 February 2022 Added tempDir to specify where temporary files are stored.
2.5.1 12 February 2022 Fixed bug 110 - crash on bad metadata line
2.5 14 November 2021 Added support for &nbsp;. exportGraphics: yes exports PNG for SVG & EPS files. Added support for EPS graphics.
2.4.3 24 October 2021 Added support for indirect links, complementing reference links.
2.4.2 18 October 2021 Added hideMetadata: style - to suppress style. items in the Processing Summary slide. Also flag overridden values in same.
2.4.1 2 October 2021 Fixed bug where code appeared in a slide's Notes slide
2.4 19 September 2021 Some simple style information added to span support. fgcolor & bgcolor hex RGB metadata values are checked for validity.
2.3.4 7 September 2021 Added SectionArrows which enables navigation buttons between Section slides. SectionArrowsColour sets the buttons' background colour.
2.3.3 27 August 2021 Added TOCStyle: plain Table Of Contents layout. Also can enable internal links in TOC and Section slides. Fixed addTableLines bug.
2.3.2 23 August 2021 Added TOCStyle: circle Table Of Contents layout. Also metadata to control Table Of Contents layout.
2.3.1 21 August 2021 Forgot to mention prev / pop in documentation for 2.3.
2.3 21 August 2021 Fixed "slide title as heading reference bug". Added Python release to runtime output. Refactored metadata handling.
2.2.5 5 August 2021 You can turn on lines after table rows and columns with addTableRowLines and addTableColumnLines. You can also do addTableLines on a slide-by-slide basis. Also addTableLineColour, addTableLineWidth, and addTableLineCount.
2.2.4 30 July 2021 You can turn on a border round a table or all cells with addTableLines. Fixed bug where slide notes appeared containing code fragments and subtitles.
2.2.3 25 July 2021 Code etc blocks can include numeric character and entity references
2.2.2 22 July 2021 Fixed bug where code blocks not initialised to none on starting a new slide
2.2.1 19 July 2021 Added AdjustTitles - to control whether md2pptx adjusts slide title positions and sizes. Made slide notes work again.
2.2 20 June 2021 Added IndentSpaces - to control, including dynamically, how many spaces represent a single level of list indentation.
2.1 21 May 2021 Added &lambda;, &mu;, &nu;, &pi, &rho. Allow more than one table or code block on a slide.
2.0.2 3 May 2021 A single code block can share a slide with a list block or a table / graphics block
2.0.1 1 May 2021 Added &times;, &percnt;, &divide;, &forall;, &exist;. Fixed 'three up graphic' layout bug.
2.0 11 April 2021 Two slide content elements on a slide, involving a major restructuring of the slide layout engine.
1.9.5 28 March 2021 Added &hellip;. Allow specification of gaps between cards. Allow specification of heading level for title slide.
1.9.4 21 March 2021 Added controls code slide foreground and background colour RGB values.
1.9.3 21 March 2021 Added controls on how many columns wide code is and fixed pitch height to width ratio.
1.9.2 16 March 2021 Added <pre>, <code>, triple backtick - with <span> colouring for <pre>. Added ways to make a no-title slide.
1.9.1 6 March 2021 Added &check; entity reference. Reworked internals with more consistent layout and getContentRec and title formatting improvements. Prereq Python 3.8.
1.9 17 February 2021 Add support to specify which slide in master. Also numbersMargin
1.8.1 10 February 2021 Card options: Rounded versus square corners. Titles above or in cards
1.8 31 January 2021 SVG support for file and web graphics
1.7.2 24 January 2021 Make vertical bars optional around image references
1.7.1 11 January 2021 Fixed bug where hyperlinks in slide titles didn't work
1.7 9 January 2021 Added support for numbered list items
1.6.3 2 January 2021 Added support for vertical cards. Also new CardTitleAlign and CardLayout metadata, plus basetextsize and basetextdecrement Dynamic Metadata items.
1.6.2 1 January 2021 Added 3 slide-level Dynamic Metadata capabilities and cardpercent metadata value.
1.6.1 29 December 2020 Added <a id= as an alternative hyperlink anchor.
1.6 22 December 2020 Added Card Slide support. Metadata keys are now case-insensitive.
1.5 7 December 2020 Pictures now can have a tooltip. You can define inter-slide links on both pictures and runs of text. You can omit the final `
1.4 23 November 2020 Task slides' slide numbers are hyperlinked to the relevant slide
1.3 20 November 2020 Glossary terms now have tooltips and hyperlinks to the relevant Glossary slide. Footnotes have hyperlinks to the relevant Footnotes slide.
1.2 3 November 2020 Support URLs for graphics. Reworked Processing Summary slide to use a flowed table.
1.1 25 October 2020 Introduce Template as a better replacement for Master - which still works. Add German characters. Better template file searching. Escape underscore. Better handling of continuation onto second and subsequent lines.
1.0 13 October 2020 Python 3, Support input filename as first command line parameter.
0.9 4 September 2020 Footnote slide support
0.8 14 June 2020 bgcolor is now style.bgcolor. Added style.fgcolor and style.emphasis.
0.7.3 24 May 2020 Allow background colouring via span elements
0.7.2 14 April 2020 Support three graphics on a slide. Added &equals; entity reference. Added tableMargin.
0.7.1 14 November 2019 Make slide titles longer. Fixed formatting issue with one-graphic-above-another table slide.
0.7 3 November 2019 Support abbr element as a glossary item. Each distinct term leads to a glossary slide entry at the back of the presentation.
0.6 8 October 2019 Support vertical pair of graphics in a table
Fixed some issues with Markdown-syntax hyperlinks
Support escaped square brackets \[ and \],&lsqb; and &rsqb; being newly-supported alternatives
0.5 12 May 2019 CriticMarkup support
0.4.5 5 May 2019 Some numeric character references
0.4.4 6 March 2019 Processing summary slide shows build date and time
0.4.3 20 January 2019 Support a few HTML entity references - punctuation and arrows.
Support split task slide sets - completed and incomplete.
Task tags are sorted.
0.4.2 13 January 2019 Tasks slide set controllable with metadata taskSlides and tasksPerSlide
0.4.1 9 January 2019 Enhanced Taskpaper support with @due, @tags, and @done, and reworked as a series of table slides.
0.4 7 January 2019 Support shrinking of table cell font and margins.
Added two-to-by-two grid of graphics on a slide.
0.3.2 3 January 2019 Support \# as a literal octothorpe/hash/pound.
Tidied up reporting.
Added superscript, subscript, strikethrough, and underline text effects.
0.3.1 3 November 2018 Fixed support for <br/> so it won't create a bullet on the new line.
0.3 22 October 2018 Added customisation for bold and italic text
0.2 3 September 2018 Added ways of controlling bullet sizes
0.1 1 April 2018 Initial Prototype

Creating Slides

Let's start with a simple example. Consider the following text.

template: Martin Template.pptx
pageTitleSize: 24
sectionTitleSize: 30

# This Is the Presentation Title Page

## This Is A Section

### This Is A Bullet Slide

* Bullet One
  * Sub-bullet A
  * Sub-bullet B
* Bullet Two
* Bullet Three

You can try it if you like. Just cut it and paste it into a file. Call it something like Example.markdown.

It will render something like this:

The first slide is special, and an almost inevitable feature of using the python-pptx library. You will probably want to remove it before publishing.

If there is at least one slide in the presentation template md2pptx uses the first one to create a processing summary. The processing summary slide shows processing options, the time and date the presentation was created by md2pptx, and metadata.

Metadata is specified in the first three lines of this sample. In general metadata is the set of lines before the first blank line. It consists of key/value pairs, with the key separated from the value by a colon.

In this case the metadata specifies a number of things:

  1. The Powerpoint file the presentation is based on is "hipodz.pptx".
  2. Each slide with a title has a title font 22 points high.
  3. Each presentation section slide has a title font 30 points high.
  4. A number of other styling-related specifications.

All of the above are optional but you will almost certainly want to specify a template. Feel free to copy Martin Template.pptx - which is included with md2pptx - and make stylistic changes.

For more on metadata see Controlling The Presentation With Metadata.

As you can see the format of each slide is fairly straightforward. How to code slides is described in the following sections.

Presentation Title Slides

You code a presentation title slide with a Markdown Heading Level 1:

# This Is the Presentation Title Slide

If you type anything in subsequent lines - before a blank line - the text will appear as extra lines in the presentation title. You might use this, for example, to add the presentation authors' details.

(You can adjust the Markdown heading level for this type of slide with TopHeadingLevel.)

Presentation Section Slides

You code a presentation section slide with a Markdown Heading Level 2:

## This Is A Section

You can code multiple lines, as with Presentation Title slides.

(You can adjust the Markdown heading level for this type of slide with TopHeadingLevel.)

Bullet Slides

Bullet slides use Markdown bulleted lists, which can be nested. This example shows two levels of nesting.

The title of the slide is defined by coding a Markdown Heading Level 3.

### This Is A Bullet Slide

* Bullet One
	* Sub-bullet A
	* Sub-bullet B
* Bullet Two
* Bullet Three

Bulleted list items are introduced by an asterisk.

NOTE: Some dialects of Markdown allow other bullet markers but md2pptx doesn't. You can be sure by coding * you have valid Markdown that md2pptx can also process correctly. For an explanation of why you have to stick to * see here.

To nest bullets use a tab character or 2 spaces to indent the sub-bullets. md2pptx doesn't have a limit on the level of nesting but Powerpoint probably does.

Terminate the bulleted list slide with a blank line.

NOTE: You can alter the number of spaces that represent each level of indenting. See Specifying How Many Spaces Represent An Indentation Level With IndentSpaces. If you use tabs they will be converted to the the appropriate number of spaces internally.

Numbered List Items

Within a bullet slide you can have numbered items. Here is an example of a slide with mixed numbers and bullets:

### This Is A Mixed Numbers And Bullets Slide

* Bullet One
	1. Numbered sub-bullet A
	1. Numbered sub-bullet B
* Bullet Two
* Bullet Three

Numbered list items are introduced with an integer, followed by a full stop.

Markdown takes care of the numbering. In the above example there are two numbered items. While the first will indeed be numbered "1" the second will be numbered "2", despite the 1. coding.

Numbering with 1. is actually a useful practice - as it makes it easier to reorder a numbered list (by moving the lines around).

Note: You can mix numbered and bulleted items in a list.

Graphics, Video And Audio slides

You can embed three kinds of media in slides:

These media items can be from your file system, or over the web.

If a local file is found a simple "missing" file message is printed.

In the case of over the web, two kinds of errors can be detected and reported:

  • The domain is unreachable, reported as a socket error.
  • The domain is reachable, but an error occurred in retrieving the file. In this case the HTTP code is reported, helping you debug whether the filename is wrong (404) or some other issue.

Graphics Slides

As with bullet slides, code the slide title as a Markdown Heading Level 3. Specify the graphic to embed with the standard Markdown image reference:

### A Graphic Slide

![](graphics/my-graphic.png)

The graphic will be scaled to sensibly fill the slide area.

If you code a string inside the square brackets it will be used as a tooltip (or screentip, in Powerpoint parlance). In Presentation Mode, when you hover over the graphic the tooltip will be displayed. Here is an example:

![Here is a tooltip](graphics/my-graphic.png)

HINT: If you want two graphics side by side use a single-row table, described here. If you want two graphics one above the other use a two-row, single-column table, described here.

Clickable Pictures

You can make a picture clickable, with an optional tooltip. This means you can click on a picture in slideshow mode to go to another slide. The tooltip is shown in slideshow mode when your mouse hovers over the picture.

Here's an example, showing both a tooltip and a clickable link.

[![Foo Fighters Sonic Highways](https://upload.wikimedia.org/wikipedia/en/6/67/Foo_Fighters_8LP_Sonic_Highways.jpg)](#sonic-highways)

Here the image reference is embedded in the clickable link:

  • The tooltip text is Foo Fighters Sonic Highways.
  • The picture's source is https://upload.wikimedia.org/wikipedia/en/6/67/Foo_Fighters_8LP_Sonic_Highways.jpg
  • The target slide has the heading reference sonic-highways.

To create a hyperlink to a slide with heading reference code something like this as the title of that slide:

### My Slide’s Title [sonic-highways]

See Hyperlinks for more on creating hyperlinks.

Graphics File References

md2pptx supports graphics references in three different formats:

  • A local file reference - ![](~/Documents/Customers/XYZCO/sysplexes.png)
  • A HTTP(S) reference - ![](http://www.anyfirm.co/banner.jpeg)
  • A data: URI reference - ![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==)

The data: URI example actually works! Try it.

For cases other than the local file, the reference - when displayed by md2pptx - is shortened to show the beginning and the end of the reference. This is to make it easy to recognise if you've accidentally repeated the reference. Here is an example:

Slides:
=======

   1     Test Title                                           --> data:image/png;base64,/9j.../Nka02WcDC6hCtKgQhCAP/9k=

For image graphics only PNG and JPEG have been tested. While the code doesn't explicitly prohibit other image file types they aren't currently supported.

Scalable Vector Graphics (SVG) format is only supported if you have installed the CairoSVG Python package - as PowerPoint doesn't support it (and nor does python-pptx). SVG files - whether from the web or a local file - are converted to a temporary PNG file first, before copying into the PowerPoint slide deck.

SVG support uses the CairoSVG library - which requires Python to be at least at the 3.6 level. md2pptx's SVG support is limited by that available in CairoSVG and so not all SVG files are supported.

If CairoSVG is not installed and md2pptx encounters an SVG graphic reference it will write a message reminding you of the need for CairoSVG. md2pptx will then immediately terminate.

Encapsulated Postscript (EPS) format is only supported if you have installed the Pillow Python package and Ghostscript - as PowerPoint doesn't support it (and nor does python-pptx). EPS files - whether from the web or a local file - are converted to a temporary PNG file first, before copying into the PowerPoint slide deck. Pillow requires Python to be at least at the 3.7 level.

You can optionally have md2pptx export the temporary PNG files. See Exporting Converted SVG And PNG Files - exportGraphics. The file name is the same as the SVG or EPS file's name, except the extension is PNG.

Notes:

  1. You can specify which directory temporary files, such as temporary graphics, are stored in - using tempDir.

  2. For graphics - whether image or vector - retrieved from the Internet md2pptx will attempt to acquire the MIME type (Content-Type HTTP header) to determine what type the graphic is:

    • PNG - image/png
    • JPEG - image/jpeg or image/jpg (though the latter is unofficial)
    • SVG - image/svg+xml or image/svg (though the latter is unofficial)
    • EPS - application/postscript

Video And Audio Slides

Videos and audio files are supported in a similar way to graphics slides. However, there is no Markdown support for embedding videos or audio files. Fortunately, Markdown processors support HTML.

Video Slides

md2pptx supports embedding videos using the HTML <video> element.

Here is an example:

<video height=300 width=400 src="waterdrop.mp4"></video>

md2pptx uses the values of the height and width elements to compute the aspect ratio of the video. In this example the ratio of the width to height is 4 to 3.

Optionally, you can code a poster attribute. This defines a static graphic to be displayed when the video isn't playing. Here's an example:

<video width="400" height="300" src="waterdrop.mp4" poster="Battery W3M.png">

Notes:

  1. Unlike with graphics specified according to Graphics Slides, the poster graphic's dimensions are not used to scale the poster graphic or the video.
  2. md2pptx supports only the simplest form of the <video> element.
Audio Slides

md2pptx supports embedding audio files using the HTML <audio> element.

Here is an example:

<audio src="audiotest.mp4"></audio>

Optionally, you can code a poster attribute. This defines a static graphic to be displayed when the audio file isn't playing. Here's an example:

<audio src="audiotest.mp4" poster="my-album-cover.png"></audio>

Notes:

  1. The HTML <audio> element does not support width or height attributes. md2pptx scales the audio file on the slide to be square.
  2. Unlike with graphics specified according to Graphics Slides, the poster graphic's dimensions are not used to scale the poster graphic or the audio file.
  3. md2pptx supports only the simplest form of the <audio> element.

Table Slides

You can create a table slide using Markdown's table format.

Code a title with a Markdown Heading Level 3. Then code a table. Here is a simple example of a table:

|Left Heading|Centre Heading|Right Heading|
|:----|:-:|--:|
|Alpha|Bravo|1|
|Charlie|Delta|2|

In this example there are three columns and three rows. The first row is the heading row. The third and fourth rows are data rows.

The second row controls the alignment of each column and their width:

  • In the first column the leading colon denotes the text is to be left-justified.
  • In the second column the colons either end denotes the text is to be centred.
  • In the third column the trailing colon denotes the text is to be right-justified.
  • According to the number of dashes the columns have widths in the ratio of 4 to 1 to 2.

In other Markdown processors the widths of the columns can't be specified in this way; The relative width specifications will be ignored.

Each cell can consist of text, which will wrap as necessary. You can't embed images in a table slide. But see here and here.

As a convenience, you can omit the final | on a line. While this isn't strictly Markdown compliant this might be helpful.

Special Case: Two Graphics Side By Side

The best Markdown fit for two graphics side by side is a single row table with two cells. md2pptx will "special case" such a table.

If you code something like this the two graphics will be placed next to each other:

|![](left-graphic.png)|![](right-graphic.png)|

A table won't be created in this case.

Don't code any headings or more than one row.

For the types of graphics supported see Graphics File References.

For how to make such graphics clickable or have a tooltip see Clickable Pictures.

Note: Regular Markdown processors don't support pictures in tables; They render the | characters literally. For this reason the vertical bars are optional.

Special Case: Two By Two Grid Of Graphics

The best Markdown fit for four graphics on a slide is a two row table with two pairs of cells. md2pptx will "special case" such a table.

If you code something like this the four graphics will be placed in two rows of two:

|![](top-left-graphic.png)|![](top-right-graphic.png)|
|![](bottom-left-graphic.png)|![](bottom-right-graphic.png)|

A table won't be created in this case.

Don't code any headings or more than two rows.

To achieve the best result some margins around the graphics are reduced.

For the types of graphics supported see Graphics File References.

For how to make such graphics clickable or have a tooltip see Clickable Pictures.

Note: Regular Markdown processors don't support pictures in tables; They render the | characters literally. For this reason the vertical bars are optional.

Special Case: Three Graphics On A Slide

The best Markdown fit for three graphics on a slide is a two row table:

  • The first row has two graphics.
  • The second row has one graphic, centred in the row.

md2pptx will "special case" such a table.

If you code something like this the three graphics will be placed appropriately:

|![](top-left-graphic.png)|![](top-right-graphic.png)|
|![](bottom-graphic.png)|

Here the layout will be a "T".

A table won't be created in this case.

Don't code any headings or more than two rows.

To achieve the best result some margins around the graphics are reduced.

There are some variants on the above scheme. For example, if you code:

|![](top-graphic.png)|
|![](bottom-left-graphic.png)|![](bottom-right-graphic.png)|

Here the layout will be an inverted "T".

You can also force left alignment or right alignment of the sole graphic in a row. For example:

|![](top-leftgraphic.png)||
|![](bottom-left-graphic.png)|![](bottom-right-graphic.png)|

will align the sole top-row graphic to the left.

For the types of graphics supported see Graphics File References.

For how to make such graphics clickable or have a tooltip see Clickable Pictures.

Note: Regular Markdown processors don't support pictures in tables; They render the | characters literally. For this reason the vertical bars are optional.

Special Case: One Graphic Above Another

The best Markdown fit for two graphics, on above the other, on a slide is a two row table with a single cell in each row. md2pptx will "special case" such a table.

If you code something like this the two graphics will be placed in two rows of one:

|![](top-graphic.png)|
|![](bottom-graphic.png)|

A table won't be created in this case.

Don't code any headings or more than two rows.

For the types of graphics supported see Graphics File References.

For how to make such graphics clickable or have a tooltip see Clickable Pictures.

Note: Regular Markdown processors don't support pictures in tables; They render the | characters literally. For this reason the vertical bars are optional.

Multi-Column Table Cells

Markdown supports cells that span more than one contiguous column. Here's an example:

|A||C|
|:-:|:-:|:-|
|Two cells?||One?|
|1|2|3|
||A|B|

In this example

  1. The empty cell in the heading line causes the "A" cell to occupy the first two columns.
  2. The empty cell after "Two Cells?" causes "Two Cells?" to occupy the first two columns.
  3. The empty cell at the beginning of the final row leads to an empty first cell. "A" is in the second column.

Card Slides

A card slide contains side-by-side panels - or cards. Each card has a title and, below that, the contents are defined using the same syntax as in Bullet Slides. In fact this slide type is derivative of the Bullet Slide type.

A card slide can look something like this:

The key features of this slide are:

  • A title, coded with Markdown Heading Level 3 syntax (###).
  • An optional panel above the cards, coded using Bullet Slides syntax.
  • A sequence of cards, coded one after the other but displayed side by side:
    • The title is coded using Markdown Heading Level 4 syntax (####).
    • The body of the card is coded using Bullet Slides syntax.

The width of each card is calculated depending on the number of cards. In this example the horizontal space is divided equally between the 4 cards.

In the above example there has been a small amount of tweaking of the format, using metadata. You can control the exact format using many tweaks:

Code Slides

You can create a slide where the body is in a monospace font, without bullets, in a number of different ways:

  • Where what you type appears exactly as you typed it - using <code>, triple backticks, or by indentation.
  • Where what you type can be coloured, using <pre> and <span> elements, together with style.fgcolor etc specifications.

When we say "code", what you're displaying could be something like a terminal screen shot, of course. What's important is that it will be rendered in a fixed-pitch font.

In each case, the heading for the slide is generally introduced with heading level 3 - ### . However you can start a slide without a heading. See Slides Without Titles for how to do this.

You can include HTML entity references and numeric character references. For example you might code &#x2776; to place ❶ next to a line of code. You could then code the same thing in a table below the code fragment, where each row explains a line of code.

Note: You can more precisely control how code slides are laid out and their colours with Code Metadata.

<code>

The HTML <code> element is supported. Surround the block of text by <code> and </code:

### This Is A Code Slide

<code>
for(i = 0; i < 10; i++){
    alert(i)
}
</code>

Note: It, as in HTML, does not support <span> elements.

Triple Backticks (```)

Triple backticks are supported. Surround the block of text by them:

### This Is A Code Slide

```
for(i = 0; i < 10; i++){
    alert(i)
}
```

Note: It does not support <span> elements.

Indented Text

Each line of the code fragment - to be displayed in a monospace font - is indented with 4 spaces:

### This Is A Code Slide

    for i in range(10):
        print(i)

Note: It does not support <span> elements.

<pre>

The HTML <pre> element is supported. Surround the block of text by <pre> and </pre:

### This Is A Code Slide

<pre>
for(i = 0; i < 10; i++){
    alert(i)
}
</pre>

Note: It, as in HTML, does support <span> elements. This is the best way to provide syntax colouring. You can use style.fgcolor, style.bgcolor, and style.emphasis to style the text. To do this you use the class attribute:

<span class="keyword">for</span> (i = 0; i < 10; i ++)

Task List Slides

You can create tasks in a subset of the Taskpaper format by coding a line that starts with a -:

- MARTIN: Complete The User Guide

If md2pptx detects any such tasks it removes them from the body of the presentation and adds them to a special set of "Tasks" slides at the end of the presentation. If no tasks are detected these slides are not created.

Taskpaper is a very flexible and simple text-based task management system. md2pptx parses anything after the - simplistically but doesn't invalidate the Taskpaper format:

  • Anything after the - leading character and before the first @ symbol, if any, is the task title.
  • Anything bracketed by @due( and ) is treated as a due date - but the date isn't actively parsed.
  • Anything bracketed by @tags( and ) is treated as a set of tags. Tags are separated by a space or a comma and they are sorted.
  • Anything bracketed by @done( and ) is treated as a completion date - but it isn't actively parsed. (An uncompleted task need not have anything in inside the bracket - or the @done could be missing.)

The task title, any due date, any tags, and any completion information, are added as a table row to the set of tasks.

Because of Taskpaper support you can't start a bullet with a -. So always start bulleted list items with a *.

Tasks on the Tasks slides are shown with the slide number they were coded on. If you click on the slide number you are taken to the corresponding slide.

Here's a more comprehensive example. Coding

- Complete abstract @due(2019-01-11) @tags(Anna,Martin)

will cause a task to appear with title "Complete abstract", a due date of "2019-01-11", and tags "Anna,Martin". In this case the task has implicitly not been completed. (It would be possible to achieve the same effect by coding @done().)

Task slides are paginated: Multiple task slides are created, each with the task slide number appended to the title, if there are more than a certain number of tasks.

You can control task slide production by specifying taskSlides and tasksPerSlide. See Controlling Task Slide Production With taskSlides and tasksPerSlide.

Slides With More Than One Content Block

md2pptx started with a very simple layout scheme: A single content block on a slide (in addition to the title). Those content blocks are:

  • A numbered or bulleted list, perhaps with cards
  • A table or else some graphics
  • A block of code

Beginning with md2pptx 2.0, this restriction has been gradually relieved.

You can code, for example, two blocks. Write them as you would for regular Markdown. Here is an example:

### Here Is A title

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

![](my-graphic.png)

The order in which, in this example, the bulleted list and the graphics blocks appear matters:

  • For horizontal layout the bulleted list would appear to the left of the graphic.
  • For vertical layout the bulleted list would appear above the graphic.

You can still only code one list block, with its optional set of cards. You can code multiple code blocks, and multiple tables.

You can code up to 10 content blocks, though in practice such a slide would probably be overcrowded.

In a text editor it's simple to reverse the order of these two blocks of content.

You can specify two aspects of splitting a slide between the various blocks of content:

  • Whether the split is horizontal or vertical, the default being vertical.
  • What proportion of the content space is the first block, and what proportion is the second.

These controls are described in Slides With Multiple Content Blocks.

Notes:

  1. You can't specify two list / card blocks on a single slide.
  2. For graphics, if you specify more than one graphic this will count as a single block. For example, two graphics side by side is a single block.

Adding Slide Notes

You can add notes to slides. In Powerpoint these appear below the main slide (and aren't shown when projecting a slide presentation).

To add a slide note leave a blank line after the slide's contents. Then add paragraphs of text. Plain text paragraphs are separated by blank lines, as is standard in Markdown.

You can use entity references, such as &percnt;. You can also use some other kinds of markup, such as hyperlinks and <abbr> elements.

Using hyperlinks when viewing slide notes in the Powerpoint application is cumbersome - as there is no equivalent for slide notes of Slide Show Mode. To follow a hyperlink in slide notes:

  1. Right click on the hyperlink.
  2. Select the Hyperlink menu item.
  3. Select Open Hyperlink.

It should then open in your browser.

Notes:

  1. It would be confusing (to the parser) to support structured items such as bulleted lists in slide notes. For this reason they are not supported.
  2. You can intersperse notes with slide contents. For example, you can follow a code block with slide note paragraphs that describe that code block. Then have another code block on the same slide, followed by its explanatory notes. All the notes will be gathered into the notes slide, which is not how other markdown processors would handle it. They would intersperse the paragraphs and the code blocks - in the order you coded them.

Slides Without Titles

Most slides have a title - and it's easy to see where such slides start. However, sometimes you want a slide without a title. For those cases you can start a slide in a two basic ways:

  • Use a horizontal rule
  • Use a level 3 heading with a non-breaking space:

The most likely use case is for code slides, though you might continue a bulleted-list slide this way.

Note: If you continue a numbered list onto a new slide its number will reset to 1.

Using A Horizontal Rule

You can code a horizontal rule in a number of ways - which all Markdown processors should be able to handle:

  • Code an HTML <hr/> element.
  • Code a line starting with ***, --- or ___. You can continue these as far to the right as you like.

Most of the time this is the technique you'll want to use but note other Markdown processors are likely to actually produce a horizontal rule.

Using A Level 3 Heading With &nbsp;

Code the following on its own line:

### &nbsp;

This has the perhaps-useful side effect of not drawing a horizontal rule in most other Markdown processors.

Hyperlinks

To code a hyperlink to an external URL in a slide code something like:

[IBM Website](https://www.ibm.com)

It will be rendered with the text "IBM Website" displayed: IBM Website. This above works for external references. To create an internal slide reference you need to do two things:

  1. Tag the heading of the target slide with a heading reference (href).
  2. Code a reference to the target slide using the href.

The above syntax is in a form called Reference Hyperlinking. You can use an alternative form - called Indirect Hyperlinking. To code an external URL using an indirect hyperlink use the form

[IBM Website][IBM]


[IBM]: https://www.ibm.com

You might prefer the indirect form to the (inline) reference form for a couple of reasons:

  • You can reuse the same link, coding it in one place.
  • You can code such a link anywhere, potentially collecting links at the end of your Markdown file.

Coding A Heading Reference On A Target Slide

Multimarkdown and md2pptx support the following way of identifying a heading reference (href):

### z15 Processor Architecture [z15-arch]

* 12 Cores Per PU Chip
    * Most of which are enabled
* 4 PU Chips per drawer
* 1-5 drawers per machine

The above is a slide with a title ("z15 Processor Architecture"). You can link to this slide using the href ("z15-arch").

An alternative method of specifying a target is like this:

### z15 Processor Architecture
<a id="z15-arch"></a>

* 12 Cores Per PU Chip
    * Most of which are enabled
* 4 PU Chips per drawer
* 1-5 drawers per machine

This method is provided because it is the only reliable within-a-document hyperlink target syntax that both GitHub and other Markdown processors support.

Coding A Hyperlink To Another Slide

You can refer to the slide in a hyperlink using the href. Here's an example:

### Attributes Of A High Performance System

* For how a high performance system is built see [here](#z15-arch)
  • The bullet links to the slide with href z15-arch.
  • You click on the word here in a presentation to move to the referred-to slide.

HTML Comments

You can use HTML-style comments, ranging over multiple lines.

Start the first line with <!--.

End the last line with -->.

md2pptx will throw away HTML comments, rather than adding them to the output file.

The one exception is the use of Dynamic Metadata. md2pptx will honour these.

NOTE: Other Markdown processors will copy the comment into the output file. Put nothing in the comments that is sensitive.

Special Text Formatting

Markdown and md2pptx allow additional ways of formatting text. The syntax md2pptx supports is a subset of what many Markdown processors allow.

To specify bold surround the text with pairs of asterisks - **bold**.

To specify italics surround the text with single asterisks - *italics*.

If you actually want an asterisk code either \* or the asterisk surrounded by spaces. (An asterisk at the end of a line need only have a preceding space.) Alternatively you can code an HTML entity reference - &lowast;.

If you actually want an octothorpe/hash/pound symbol (rendered "#") code \#.

You can use bold and italics syntax to change the colour of highlighted text. See here for more.

To specify a monospace font use the back tick character - ` - at the start and end of the text run.

To force a line break code <br/>. This, being HTML, is legitimate in Markdown and will be treated as a line break. I don't want one here so I won't code one here.

Some other HTML-originated text effects work - as Markdown allows you to embed HTML (elements and attributes):

Effect HTML Element Example Produces
Superscript sup x<sup>2</sup> x2
Subscript sub C<sub>6</sub>H<sub>12</sub>O<sub>6</sub> C6H12O6
Underline ins this is <ins>important</ins> this is important
Strikethrough del this is <del>obsolete>/del> this is obsolete

Using HTML <span> Elements To Specify Text Colours And Underlining

You can set the background or foreground colour of a piece of text. To do this use the <span> HTML element:

  • You can use <span class= "..." > - which is probably more compact but less direct.
  • You can use <span style= "..." > - which is more direct but less compact.

Using HTML <span> Elements with class

Where the same styling needs to be applied to multiple pieces of text the class attribute is probably the most appropriate. Here is an example:

I would like to highlight <span class="yellow">this bit</span> but not **this** bit.

In this example the span element specifies a class attribute. The class name must match one specified in the metadata using one of

If you coded metadata

style.fgcolor.yellow: FFFF00

the result would be something like this:

I would like to highlight this bit but not this bit.

Note: A fragment of text in a span can't use any other text effect, such as bolding or italics.

The class name can be specified with double quotes, single quotes, or no quotes at all.

If you want to be able to process the text using a normal Markdown processor you can code Cascading Style Sheet (CSS) using the HTML <style> element. md2pptx will ignore any HTML after the metadata and before the first real Markdown text. For example:

<style>
.mytest{
    text-decoration: underline;
    color: #FF0000;
    background-color: #FFFF00;
    font-weight: bold;
    font-style: italic;

}
</style>

The above uses only the style elements that md2pptx supports with style. metadata. It relies on you coding

<span class="mytest">Here is some text</span>

for example - as it uses the class mytest.

Using HTML <span> Elements with style

You can specify a limited number of types of styling:

  • Foreground colour with color
  • Background colour with color
  • Underlining with text-decoration: underline
  • Bold with font-weight: bold
  • Italic with font-style: italic

Here is an example:

Here's <span style="font-weight: bold;font-style: italic;color: #0000FF;">blue bold italic</span> text.

Notice the color specification is in Hexadecimal RGB (Red Green Blue) format. CSS colour names are not supported.

HTML Entity References

md2pptx supports a few HTML entity references:

Entity Reference Character Entity Reference Character Entity Reference Character
&lt; < &larr; ← &auml; ä
&gt; > &rarr; → &Auml; Ä
&ge; ≥ &uarr; ↑ &uuml; ü
&le; ≤ &darr; ↓ &Uuml; Ü
&asymp; ≈ &harr; ↔ &ouml; ö
&Delta; Δ &varr; ↕ &Ouml; Ö
&delta; δ &nearr; ↗ &szlig; ß
&sim; ∼ &nwarr; ↖ &euro; €
&lowast; ∗ &searr; ↘ &hellip; …
&semi; ; &swarr; ↙ &percnt; %
&colon; : &lsqb; [ &divide; ÷
&amp; & &rsqb; ] &forall; ∀
&comma; , &infin; ∞ &exist; ∃
&check; ✓ &times; × &lambda; λ
&mu; μ &nu; ν &pi; π
&rho; ρ &nbsp; non-breaking space &dash; ‐

Numeric Character References

md2pptx supports a few HTML numeric character references:

  • Some like &#223; - with 3 or 4 numeric digits. (This produces the character 'ß').
  • Some like &#x03A3; - with 4 hexadecimal digits. (This produces the character 'Σ').

(Some emoji work. For example you can paste 🦖 in to the source.)

Escaped Characters

md2pptx supports a few escaped characters. Of most interest are the two square bracket characters:

  • \[
  • \]

You can also escape the underscore character:

  • \_

CriticMarkup

md2pptx supports CriticMarkup for text. To quote from their home page:

CriticMarkup is a way for authors and editors to track changes to documents in plain text. As with Markdown, small groups of distinctive characters allow you to highlight insertions, deletions, substitutions and comments, all without the overhead of heavy, proprietary office suites.

md2pptx supports all five markup elements. In common with other CriticMarkup processors, md2pptx shows the markup and merely colours the markup and marked up text appropriately:

  • Insertion - {++ and ++} - rendered in green.

    For example {++ This text was inserted ++}

  • Deletion - {-- and --} - rendered in red.

    For example {-- This text was deleted --}

  • Comment - {>> and <<} - rendered in blue.

    For example {>> This text is a comment <<}

  • Replacement - {~~, ~> ~~} - rendered in orange.

    For example {~~old text~>replacement text~~}

  • Highlight - {== and ==} - rendered in purple.

    For example {== This is a highlight ==}

In the above examples the deletions, insertions, replacements etc don't actually happen; They are just marked. Editing tools are needed to actually perform these actions, once the reviewer's comments have been accepted.

Creating A Glossary Of Terms

You can use the HTML abbr element to generate a glossary entry. For example,

<abbr title='British Broadcasting Corporation'>BBC</abbr>

In this example the glossary term is "BBC" and its definition is "British Broadcasting Corporation".

One or more Glossary Table slides will appear at the end of the presentation if any such terms are defined. When you create a glossary entry three things will happen:

  • Both the term and its definition will appear in the glossary.
  • The term will appear in the slide with the abbr element - with the appearance of a hyperlink element, which you can click on to get to the relevant Glossary slide.
  • If you hover over the term for a second or two the definition of the term will appear as a tooltip.

If you define the term more than once only the first use will be included in the glossary. All uses of the term will appear in the normal slides.

Each Glossary Table slide comprises two columns: A narrow column with the terms (or acronyms), and a wider column with their definitions (or meanings).

In Glossary Table slides the definitions are sorted alphabetically, upper case before lower case.

If you use the abbr HTML element most markdown processors will treat it as HTML and hovering over the term will reveal the definition. However, while md2pptx can cope with e.g. <br/> elements in a glossary definition most markdown processors can't.

You can control various aspects of the glossary's appearance using metadata. How to is described here.

Because md2pptx's support uses hyperlinks you might want to adjust your template so that taken hyperlinks are the same colour as not-yet-taken ones. This is something md2pptx can't do for you. You can change these colours under "Themes" in the Slide Master editor.

Creating Footnotes

You can create and reference footnotes.

Creating A Footnote

To define a footnote code [^name]: on a new line. The remainder of the line will be the footnote text.

If you have defined footnotes one or more Footnotes slides will be added to the end of the presentation.

Footnotes are automatically numbered, starting with 1.

Referring To A Footnote

To refer to a footnote code [^name]. The footnote's number (automatically generated) will appear like so:

    This is a footnote reference4.

If the name doesn't match a footnote a question mark will be printed instead of the footnote number.

If you click on a footnote number you will be taken to the appropriate Footnotes slide.

Controlling The Presentation With Metadata

You can control some aspects of md2pptx's processing using metadata.

Specifying Metadata

You specify "whole presentation" metadata in the lines before the first blank line. It consists of key / value pairs, with the key separated from the value by a colon. Keys are case insensitive. In this User Guide they are capitalised to aid comprehension. For example, baseTextDecrement is treated the same as basetextdecrement.

While some Markdown processors handle metadata, most ignore it. Conversely, while md2pptx will generally print all the metadata it encounters on the first slide (if the template presentation contains at least 1 slide), it will practically ignore metadata it doesn't understand.

Also any line containing invalid metadata (that is not in the form key : value) will be flagged as an error but otherwise ignored.

"Whole presentation" refers to metadata that applies to every slide in the presentation - unless overridden. Whole presentation metadata items are described in Metadata Keys.

Some metadata items can be overridden dynamically - in the middle of the presentation. md2pptx will only support these where it makes sense to. These keys are described in Dynamic Metadata.

Processing Summary

As described in Creating Slides, md2pptx will populate the first slide in the template file with metadata information (if such a slide exists). This slide will contain a table with all the "whole presentation" metadata keys and their values. Its format will adjust to fit all the metadata items.

Notes

  1. If you override a "whole presentation" metadata item by a dynamic metadata specification the key and value in this table will be coloured blue. An asterisk will be appended to the metadata value.
  2. You can suppress style. metadata items by specifying the metadata item hideMetadata: style. In the md2pptx developer's experience style. metadata items can become numerous and could obscure more important items in the Processing Summary slide. The default is not to hide such items.

Metadata Keys

The following sections describe each of the metadata keys.

Slide Numbers - numbers

md2pptx can add slide numbers. These are generated by md2pptx itself (or hardcoded) and are not the same as ones you can turn on in a footer.

The default value is no. You can turn them on for all slides with yes or non-title slides with content.

Example:

numbers: yes

Page Title Size - pageTitleSize

You can specify the point size of each slide that isn't a section divider or title slide. The size is specified in points.

Example:

pageTitleSize: 24

The default is 30 points.

You can override this value on a slide-by-slide basis with Dynamic PageTitleSize.

Section Title Size - sectionTitleSize

You can specify the point size of the title text for each slide that's a section divider or title slide. The size is specified in points.

Example:

sectionTitleSize: 42

The default is 40 points.

Section Subtitle Size - sectionSubtitleSize

You can specify the point size of the subtitle text for each slide that's a section divider or title slide. The size is specified in points.

The subtitle text is the second and subsequent lines of the title - generally a separate text shape on the slide.

Example:

sectionSubtitleSize: 24

The default is 28 points.

Monospace Font - monoFont

You can specify which font to use for monospaced text - such as on code slides.

Example:

monoFont: Arial

The default is Courier.

Margin size - marginBase and tableMargin

You can increase or decrease the margin around things - in decimal fractions of an inch.

For a table you can specify the left and right margins using tableMargin. For everything else use marginBase.

Example:

marginBase: 0.5

The default is 0.2 (inches).

You can do this dynamically (on a slide-by-slide basis with marginBase or tableMargin.

Controlling Adjusting Title Positions And Sizes - AdjustTitles

By default md2pptx will adjust the positions and sizes of slide elements - to create a uniform, tidy experience. Sometimes, though, you might not want this adjustment to happen. For elements other than titles this is unlikely to be the case - as that would interfere with multi-element layouts.

You can disable adjusting the positions and sizes of slide titles:

AdjustTitles: no

The default is yes.

Associating A Class Name with A Background Colour With style.bgcolor

You can use HTML <span> elements to set the background colour, as described in Using HTML <style> Elements To Specify Text Colours And Underlining.

Here is an example:

style.bgcolor.yellow: FFFF00

In this example the class "yellow" is associated with a background colour, defined in RGB terms as hexadecimal FFFF00, which is:

  • 255 of red
  • 255 of green
  • 0 of blue

which is in fact yellow.

Associating A Class Name with A Foreground Colour With style.fgcolor

You can use HTML <span> elements to set the foreground colour, as described in Using HTML <style> Elements To Specify Text Colours And Underlining.

Here is an example:

style.fgcolor.red: FF0000

In this example the class "red" is associated with a foreground colour, defined in RGB terms as hexadecimal FF0000, which is:

  • 255 of red
  • 0 of green
  • 0 of blue

which is in fact red.

Associating A Class Name With Text Emphasis With style.emphasis

You can use HTML <span> elements to bold text, make it italic, or underline it - as described in Using HTML <style> Elements To Specify Text Colours And Underlining.

Here is an example:

style.emphasis.important: bold underline

In this example the class "important" is associated with bolding the text and underlining it.

You can also use italic.

As the example shows, separate the emphasis attributes with a space.

Template Presentation - template

You can specify a different template file to create the presentation from than the one supplied with python-pptx. The one supplied with md2pptx is a very good one to work from:

template: Martin Template.pptx

If you want to create your own template you probably want to take Martin Template.pptx and modify it. See Modifying The Slide Template for more information on how to do so.

(For compatibility purposes, you can continue to use master instead of template. It's probably better practice, though, to use template.)

Templates are searched for in the following sequence:

  1. Using the name as given. For example hipodz.pptx will search the current directory.
  2. In the md2pptx installation directory.

Specifying An Abstract Slide With abstractTitle

You can arrange for a single-level bulleted list slide to be formatted specially - as an abstract.

Instead of each list item having a bullet, it is treated as a paragraph. This is more appropriate for an abstract slide. (An extra blank paragraph is added between each paragraph - to space it out.)

To indicate an abstract slide code

abstractTitle: Abstract

Any slide with the title matching the value of abstractTitle will be rendered as an abstract slide.

Specifying Text Size With baseTextSize And baseTextDecrement

You can control the size of text - in table slides, code slides, and bulleted list slides - with two metadata tags: baseTextSize And baseTextDecrement. If you don't specify baseTextSize the base presentation's font sizes are used.

If you specify a baseTextSize value code, tables, and the top-level bullet use this size, which is specified in points. Further, if you specify baseTextDecrement each successive level of bullets' font size is decremented by this number of points. The default for baseTextDecrement is 2 points.

For example, if you code

baseTextSize: 20
baseTextDecrement: 1

the top-level bullet uses a 20 point font, the next level down a 19 point font, and so on.

If you just coded

baseTextSize: 20

the top-level bullet uses a 20 point font, the next level down a 18 point font, and so on.

You can specify these dynamically. See here and here. You might want to do this to fine tune a particularly sparse or crowded page.

Specifying Bold And Italic Text Colour With BoldColour And ItalicColour

You can modify how md2pptx formats bold and italic colours:

  • To specify the colour of bold text use BoldColour (or BoldColor).
  • To specify the colour of italic text use ItalicColour (or ItalicColor).

For example:

BoldColour: ACCENT 1

Will cause text marked like so **I am bold** to be rendered in the presentation's smartmaster's "Accent 1" colour.

The values you can use for BoldColour and ItalicColour are:

  • NONE
  • ACCENT 1
  • ACCENT 2
  • ACCENT 3
  • ACCENT 4
  • ACCENT 5
  • ACCENT 6
  • BACKGROUND 1
  • BACKGROUND 2
  • DARK 1
  • DARK 2
  • FOLLOWED HYPERLINK
  • HYPERLINK
  • LIGHT 1
  • LIGHT 2
  • TEXT 1
  • TEXT 2
  • MIXED

As you can probably guess, these are standard values for python-pptx and, ultimately, PowerPoint.

Note: For the values you can use any capitalisation you like (or none). e.g. ItalicColor: dark 1.

Specifying Bold And Italic Text Effects With BoldBold And ItalicItalic

You can modify how md2pptx formats bold and italic text.

If you don't want bold text to actually be bold code

BoldBold: no

If you don't want italic text to actually be italic code

ItalicItalic: no

The default for both of these is, of course, yes so that bold text is bold and italic text is italic.

These options were added so that BoldColour and ItalicColour could just become colour effects. See here.

Controlling Task Slide Production With taskSlides and tasksPerSlide

Before unleashing your presentation on the world you probably want to remove the Task List slides from it. You can control what tasks are shown, if any, with taskSlides. It can take four different values:

  • all (the default) which shows both complete and incomplete tasks.
  • none which hides the task list slides altogether.
  • done which shows completed tasks only.
  • remaining which shows only tasks that haven't been completed.
  • separate which separates the tasks into slides with completed tasks and slides with incomplete tasks.

A completed task is one where the @done attribute has been coded with something inside the brackets. An incomplete task is one where either the @done attribute wasn't coded or there is nothing inside the brackets.

For example, to suppress all task slides code

taskSlides: none

Though you wouldn't normally need to do this, you can control how many tasks appear on a slide with tasksPerSlide. For example, coding

tasksPerSlide: 10

will limit the numberof tasks on a slide to 10. The default is 20 tasks per slide.

Controlling Glossary Slide Production With glossaryTitle, glossaryTerm, glossaryMeaning,glossaryMeaningWidth, and glossaryTermsPerPage

Creating A Glossary Of Terms describes how you can use the abbr element to generate a glossary of terms.

You can control various aspects of the appearance of the Glossary Slide(s) using the following metadata items.

For example, coding

glossaryTitle: Definitions

will cause the Glossary Slide title to be "Definitions". The default is "Glossary".

Coding

glossaryTerm: Acronym

will cause the first heading of the table in the Glossary Slide to be "Acronym". The default is "Term".

Coding

glossaryMeaning: Definition

will cause the second heading of the table in the Glossary Slide to be "Definition". The default is "Meaning".

Coding

glossaryMeaningWidth: 3

will cause the width of the second column in the table to be three times that of the first column.

Coding

glossaryTermsPerPage: 10

will cause the maximum number of glossary items on a Glossary slide to be 10. If there are more terms, a second slide will be created. And so on. The default is 20.

Specifying How Much Space To Reserve For Slide Numbers With NumbersHeight

You can override the default space left at the bottom of the slides - for slide numbers or maybe a custom footer:

NumbersHeight: 1.0

This specifies to reserve 1.0 inches of vertical space. The default is 0.4 inches.

You can do this dynamically (on a slide-by-slide basis) with numbersHeight.

Specifying How Many Spaces Represent An Indentation Level With IndentSpaces

While the default for signifying each level of indentation for bullets is two spaces, you can change it by coding IndentSpaces for metadata. For example:

IndentSpaces: 4

You can change the value of IndentSpaces on a slide-by-slide basis, perhaps because you are including material from elsewhere that uses a different value. See Dynamic IndentSpaces.

Specifying Where Temporary Files Are Stored With tempDir

You can specify which directory temporary files are stored in. For example:

tempDir: ~/Temp

The above stores temporary files in the Temp subdirectory of the user's home directory. As you can see from this example directory names are expanded.

Deleting The First (Processing Summary) Slide - with DeleteFirstSlide

Sometimes you will want to review the Processing Summary slide - which is the first slide in the presentation. Sometimes you won't.

To remove it specify:

removeFirstSlide: yes

The default is no.

Note: If you don't have a Processing Summary slide - perhaps because the slide master you used doesn't have a slide - the first slide would still be removed if you specified removeFirstSlide: yes. This is probably not what you want to have happen.

Table Metadata

Shrinking Tables With compactTables

You can reduce the size of a table on the slide with compactTables. If you specify a value larger than 0 two things will happen:

  • The font will use whatever point size you specify.
  • The margins around the text in a cell will be reduced to 0.

For example, to remove the margins and reduce the font size to 16pt code

compactTables: 16

You can override this value with Dynamic Metadata.

Adjusting Table Heading Font Size With tableHeadingSize

You can adjust the size of a table heading on the slide with tableHeadingSize. If you specify a value larger than 0 the table heading line font will use whatever point size you specify.

For example, to increase the table heading font size to 24pt code

tableHeadingSize: 24

You can override this value with Dynamic Metadata.

Adding Lines Round Tables And Cells With addTableLines

You can add lines to tables in two ways:

addTableLines: box

will add a black border round the entire table.

addTableLines: both

will add a black border round all the cells, and effectively the table.

The default is addTableLines: no which doesn't add any table lines.

You can override this metadata item with Dynamic Metadata.

Note: This capability never removes lines - for example if they are present in the template presentation.

Adding Lines After Table Rows And Columns With addTableRowLines And addTableColumnLines

You can add lines to the right of specific columns and below specific rows with addTableColumnLines and addTableRowLines, respectively. For example

addTableColumnLines: 1 3

specifies tables will have vertical lines to the right of the first and third columns. (Column numbers start at 1.)

Similarly

addTableRowLines: 1

specifies tables will have horizontal lines below the first row (often a header).

You can override both these metadata items with Dynamic Metadata.

Note: This capability never removes lines - for example if they are present in the template presentation.

Specifying What The Added Table Lines Look Like With addTableLineColour, addTableLineCount and addTableLineWidth

By default added table lines are black, narrow, and consist of a single line. You can change all three of these.

To change the colour specify the RGB value like this:

addTableLineColour: FF00FF

which will make the added lines purple. (This example is full-on red and full-on blue mixed to make purple.)

To double the width of the added lines specify a width multiplier (in this case 2) like this:

addTableLineWidth: 2

To make the added lines pairs specify:

addTableLineCount: 2

In this case the only valid values are 1 and 2x.

You can specify all three of these on a table-by-table basis. See Dynamic Metadata.

Controlling Whether Empty Table Cells Cause Column Spanning - SpanCells

For some use cases you don't want an empty table cell to cause the cell to the left to expand into it. To prevent this code:

spanCells: no

The default is yes.

You can override this value at the slide level with Dynamic SpanCells.

Card Metadata

Card Background Colour - CardColour

You can specify which of the theme colours to use for the background of each card in a Card Slide - using CardColour (or CardColor). For example:

CardColour: BACKGROUND 2

If you don't specify this the default text box background colour - from the template - will be used.

Card Border Colour - CardBorderColour

You can specify which of the theme colours to use for the border of each card in a Card Slide - using CardBorderColour (or CardBorderColor).For example:

CardBorderColour: TEXT 1

If you don't specify this the cards won't have a border.

Card Border Width - CardBorderWidth

You can specify the thickness of the border (in points) of each card in a Card Slide - using CardBorderWidth. For example:

CardBorderWidth: 1

If you don't specify this the cards will use the default text box border width - from the template.

Card Title Size - CardTitleSize

You can specify the size of the font (in points) for the cards' title - using CardTitleSize. For example:

CardTitleSize: 15

If you don't specify this the card titles will be 2/3 the size of the slide's title.

Card Shadow - CardShadow

You can specify whether a card has a shadow - using CardShadow. For example:

CardShadow: yes

If you don't specify this the cards won't have a shadow - unless the default text box style is to have a shadow.

Card Size - CardPercent

You can control the vertical space used by cards - as a percentage of the content area. The default is 80%.

Here is an example:

CardPercent: 70

You can override this value on a slide-by-slide basis with Dynamic CardPercent.

Card Layout Direction - CardLayout

By default md2pptx lays out cards across the slide. This is called "horizontal layout" - and is generally a good use of slide space. But it's not what many Markdown processors do with Heading Level 4 (####). They tend to lay out vertically, even though this is generally a poorer use of slide "real estate".

To specify horizontal card layout code:

CardLayout: horizontal

To specify vertical card layout code:

CardLayout: vertical

You can override this value on a slide-by-slide basis with Dynamic CardLayout.

Card Title Alignment - CardTitleAlign

By default md2pptx centres card titles above the corresponding card. Generally this looks best for the horizontal card layout.You can override this - perhaps to make titles on a vertical card layout slide left aligned.

To specify left card title alignment code:

CardTitleAlign: left

You can specify left, right, or center or centre. You can abbreviate these to l, r, or c.

You can override this value on a slide-by-slide basis with Dynamic CardTitleAlign.

Card Title Position - CardTitlePosition

By default md2pptx places each card's title above the card body. You can override this.

To specify the cards' titles will be inside the card body, at the top, code:

CardTitlePosition: inside

The default value is above.

You can override this value on a slide-by-slide basis with Dynamic CardTitlePosition.

Card Shape - CardShape

By default md2pptx renders each card with a rounded card body. You can override this.

To specify the cards' bodies will be squared off, at the top, code:

CardShape: squared

The default value is rounded.

You can override this value on a slide-by-slide basis with Dynamic CardShape.

Card Horizontal Gap - CardHorizontalGap

You can adjust the horizontal space between cards that are laid out side by side using CardHorizontalGap. For example:

CardHorizontalGap: 0.2

The default is 0.25 inches.

You can override this on a slide-by-slide basis with Dynamic Horizontal Gap.

Card Vertical Gap - CardVerticalGap

You can adjust the vertical space between cards that are laid out one above the other using CardVerticalGap. For example:

CardVerticalGap: 0.05

The default is 0.1 inches.

You can override this on a slide-by-slide basis with Dynamic Vertical Gap.

</>

Code Metadata

You can adjust how code slides display their content.

Code Column Count - CodeColumns

You can adjust how wide the text box the code is displayed in using CodeColumns. For example:

CodeColumns: 70

The default value is 80.

You can override this on a slide-by-slide basis with Dynamic CodeColumns.

Fixed Pitch Height To Width Ratio - FPRatio

md2pptx assumes the height of a column is 1.2 times its width. You can adjust this ratio with FPRatio:

FPRatio: 1.1

You can override this on a slide-by-slide basis with Dynamic FPRatio.

Foreground Colour - CodeForeground

The default foreground colour for code slides is black (#000000 in RGB terms). You can override this by specifying an RGB colour, such as white:

CodeForeground: FFFFFF

You can override this on a slide-by-slide basis with Dynamic CodeForeground.

Background Colour - CodeBackground

The default background colour for code slides is white (#FFFFFF in RGB terms). You can override this by specifying an RGB colour, such as black:

codeBackground: 000000

You can override this on a slide-by-slide basis with Dynamic codeBackground.

Slide Heading Levels - TopHeadingLevel

The usual heading levels for different types of slides are as follows:

Level Slide type
1 Presentation title
2 Section title
3 Content
4 Card

However, you might need to "demote" all these slide types to, say:

Level Slide type
2 Presentation title
3 Section title
4 Content
5 Card

This might be, for example, because the same Markdown is destined for a formal publication, where the top level heading is reserved for the publication's title. To achieve this demotion you only need to specify the top level in the slide hierarchy:

TopHeadingLevel: 2

The other heading levels will be adjusted accordingly.

Note: You obviously need to code the Title Slide at Heading Level 2, for example.

Slides With Multiple Content Blocks

This section describes how you can control the layout of slides with multiple blocks of content.

See Slides With More Than One Content Block for how to specify multiple blocks of content on a slide

Horizontal Or Vertical Split - ContentSplitDirection

You can specify whether the blocks of content are to be vertically or horizontally arranged with

ContentSplitDirection: vertical

or

ContentSplitDirection: horizontal

You can use h or v for short. You can also use ContentSplitDirn.

You can override this on a slide-by-slide basis with Dynamic ContentSplitDirection.

The default value is vertical.

Split Proportions - ContentSplit

You specify the split between the blocks as proportions. For example:

ContentSplit: 1 4

will make the first block a quarter the height (or width) of the second. Specify proportions using integers.

You can override this on a slide-by-slide basis with Dynamic ContentSplit.

The default value is such as to make each block have equal space.

Graphics Metadata

Exporting Converted SVG And PNG Files - exportGraphics

By default md2pptx does not export SVG and EPS files converted to PNG. (md2pptx handles SVG and EPS graphics by converting them to PNG format.) You can save the converted graphics to PNG by specifying:

exportGraphics: yes

Table Of Contents And Section Slide Metadata

If you have a slide in a certain format you can convert it to a Table Of Contents slide. This slide can be "Chevron Style", "Circle Style", or "Plain Style".

In addition to building the Table Of Contents slide, for Chevron and Circle styles, each Section Slide replicates the Table Of Contents slide but with the current section's title highlighted. The examples below will make this clearer.

The format required is a bulleted list slide with each section title listed as a top level bullet. For example:

### Topics

* [A Section](#a-section)
* [Another Section](#another-section)
* [Yet Another Section](#yet-another-section)
* [A Much Longer Section Title](#a-much-longer-section-title)
* [An Even Longer Giant Section Title](#an-even-longer-giant-section-title)
* [Let's Do It Again](#lets-do-it-again)
* [And One More Time](#and-one-more-time)

You will recognise each entry as an internal link. Perhaps the easiest way to create such a piece of Markdown is with mdpre with its =toc capability. It will automate gathering the links and Section slide titles.

When processing this slide md2pptx will recognise it as a Table Of Contents slide because of the slide title "Topics". It will build a list of headings from the bullets. With Chevron and Circle styles, when md2pptx sees a Section slide whose title matches one of the titles in the Table Of Contents slide's bullets it creates a similar slide to the Table Of Contents slide, but with this section highlighted.

NOTES:

  • Ensure only one slide has the same title as the Table Of Contents slide. Otherwise md2pptx will attempt to render the other slides as if they were a Table Of Contents slide.
  • Ensure the Section slides' titles are unique. Otherwise more than one chevron will be highlighted on the relevant section slide.
  • The style of the Table Of Contents and Section slides is controlled with tocStyle.
  • You don't have to use "Topics" as the title of the Table Of Contents slide. You can control this with tocTitle.
"Chevron Style" Table Of Contents

To create a "Chevron Style" Table Of Contents slide and Section slides code:

tocStyle: chevron

If you create a "Chevron Style" Table Of Contents slide, it will look something like this:

If you specify tocStyle: chevron the Section slides will be rendered something like this:

Here the section is highlighted by removing the background.

In the above pictures live links are disabled and default rendering options have been taken.

"Circle Style" Table Of Contents

To create a "Circle Style" Table Of Contents slide and Section slides code:

tocStyle: circle

If you create a "Circle Style" Table Of Contents slide, it will look something like this:

If you specify tocStyle: circle the Section slides will be rendered something like this:

Here the section is highlighted by removing the background and emphasising the circle itself.

In the above pictures live links are disabled and default rendering options have been taken.

"Plain Style" Table Of Contents

The purpose of Plain Style is to create a Table Of Contents slide with each presentation section listed as a live link. Unlike with Chevron and Circle styles, Plain Style does not affect Section slides.

To create a "Plain Style" Table Of Contents slide and Section slides code:

tocStyle: plain

If you create a "Plain Style" Table Of Contents slide, it will look something like this:

Note: With Plain Style, Section slides are unaffected; They are rendered as if no Table Of Contents functions were used.

Table Of Contents Style - tocStyle

There are three styles of Table Of Contents and Section slide you can specify:

  • tocStyle: chevron
  • tocStyle: circle
  • TOCStyle: plain
Table Of Contents Title - tocTitle

If your Table Of Contents slide's title is something other than "Topics" you need to tell md2pptx what title to match, additionally coding something like

tocTitle: Agenda

md2pptx will look for this title on a slide instead of "Topics" and use the matching slide to create a Table Of Contents slide.

Table Of Contents Live Links - tocLinks

You can enable live links in Table Of Contents and Section slides for Chevron and Circle styles. (Links are always live in Plain style.) In a Powerpoint slide show clicking on an item in the Table Of Contents slide or a Section slide takes you to the Section slide that is the link's target.

By default live links are not enabled - for compatibility with existing presentations.

Enable live links by coding

tocLinks: yes

Note: You cannot control the colour of links in Powerpoint. For that reason you might need to change the background colour of items using TOCItemColour.

Table Of Contents Item Height - TOCItemHeight

You can control the height of the items with TOCItemHeight. Coding

tocItemHeight: 1.5

leads to each item being 1.5 inches high.

For Chevron the default is 1 inch high. For Circle the default is 1.25 inches.

Chevron items are 2.5 times as wide as they are high. Circle items are the same width as they are high.

Table Of Contents Item Colour - TOCItemColour

For Chevron and Circle Table Of Contents styles you can control the background colour of the items with TOCItemColour (or TOCItemColor). Coding

tocItemColour: E0E0FF

leads to each item's background colour being pale blue. This is a hexadecimal RGB (Red, Green, Blue) value.

If you don't specify this the default Powerpoint background colour for shapes is used.

This option was introduced because when live links are used in Table Of Contents and Section slides the link text might be nearly invisible.

Note: This option doesn't affect the background colour of the highlighted item on a Section slide; That remains unfilled.

Table Of Contents Row Gap - TOCRowGap

You can control the vertical spacing between rows of items with TOCRowGap. Coding

tocRowGap: 0.5

leads to the vertical gap between rows being 0.5 inches.

The default is 0.75 inches.

Table Of Contents Font Size - TOCFontSize

You can adjust the font size for the Table Of Contents entries with TOCFontSize. Coding

tocFontSize: 10

leads to the font size being 10 points.

For Chevron the default is 14pt. For Circle the default is 12pt.

Section Navigation Buttons - SectionArrows

You can enable navigation buttons for Section slides - if you have Table Of Contents enabled. If you do the result is something like this:

The three buttons are:

  • To previous section slide
  • To the table of contents slide
  • To the next section slide

Buttons which make no sense - such as the last Section slide having a forward button - are suppressed.

Coding

sectionArrows: yes

enables this feature. The default value is no.

You can specify the background colour for the buttons with SectionArrowsColour.

Section Navigation Button Colour - SectionArrowsColour

You can set the background colour of the buttons specified with SectionArrows.

You probably want to match any colour specified with TOCItemColour.

To do this use SectionArrowsColour (or SectionArrowsColor).

Coding

sectionArrowsColour: E0E0FF

leads to each item's background colour being pale blue. This is a hexadecimal RGB (Red, Green, Blue) value.

If you don't specify this the default Powerpoint background colour for shapes is used.

Dynamic Metadata

md2pptx can alter some in-effect settings, starting at a particular slide. Straight after the heading code a special form of (HTML) comment like so:

### Origins Of Mainframe, Performance, Topics Podcast
<!-- md2pptx: compacttables: 14 -->

The use of md2pptx: in the comment tells md2pptx there is a Dynamic Metadata statement embedded in the comment.

Here are the values you can specify for the metadata:

  • pres - revert to the presentations's value (if specified). If, at the beginning of the presentation, you didn't specify a value for this metadata item it will be the md2pptx default that will be in effect.
  • default - revert to the md2pptx default.
  • prev or pop - use the previous value, popping the stack as you do.
  • Any other value - used literally.

If you dynamically change a metadata value the new value will remain in effect for the remainder of the presentation, unless changed again.

Note: After tweaking a slide you might well want to revert to your presentation's overall value (or even the md2pptx default). Instead of this you might use prev orpop, though these are destructive.

Tables

CompactTables

You can override the presentation CompactTables metadata value - perhaps to decrease the font size for a particularly crowded table slide:

<!-- md2pptx: compacttables: 12 -->

TableHeadingSize

You can override the presentation TableHeadingSize metadata value - perhaps to increase the font size for a particular table slide:

<!-- md2pptx: tableheadingsize: 36 -->

addTableLines

You can override the presentation AddTableLines specification on a table-by-table basis:

<!-- md2pptx: addtablelines: box -->

addTableColumnLines And addTableRowLines

You can override the presentation AddTableRowLines and AddTableColumnLines specifications on a table-by-table basis:

Here is an example of adding horizontal lines below rows 1 and 4:

<!-- md2pptx: addtablerowlines: 1 4 -->

Here is an example of adding vertical liness to the right of column 2:

<!-- md2pptx: addtablecolumnlines: 2 -->

Added Table Line Attributes

You can override the presentation Added Table Line Attributes on a table-by-table basis. Here are some examples:

<!-- md2pptx: addtablelinecolour: 00FF00 -->

turns the added lines green.

<!-- md2pptx: addtablelinewidth: 4 -->

makes the added lines 4 times wider than normal.

<!-- md2pptx: addtablelinecount: 2 -->

makes the added lines each appear as a pair of lines.

SpanCells

You can override the presentation SpanCells value:

<!-- md2pptx: spancells: yes -->

You might do this if the presentation generally tolerates multi-column table cells but this table doesn't.

Cards

CardPercent

You can override the presentation CardPercent metadata value - perhaps to allow room for more card content:

<!-- md2pptx: cardpercent: 90 -->

CardLayout

You can override the presentation CardLayout metadata value - perhaps to make an individual card slide vertical when most are horizontal:

Either vertical or horizontal can be specified.

<!-- md2pptx: cardlayout: vertical -->

CardTitleAlign

You can override the presentation CardTitleAlign metadata value - perhaps to make an individual card slide's titles left-aligned when most are centred:

<!-- md2pptx: cardtitlealign: l -->

CardTitlePosition

You can override the presentation CardTitlePosition metadata value - perhaps to make an individual card slide's titles inside the cards when most are above:

<!-- md2pptx: cardtitleposition: insde -->

CardShape

You can override the presentation CardShape metadata value - perhaps to make an individual card slide's cards have square corners when most are rounded:

<!-- md2pptx: cardshape: squared -->

CardHorizontalGap

You can override the presentation CardHorizontalGap metadata value - perhaps to squeeze the gaps between cards:

<!-- md2pptx: cardhorizontalgap: 0.05 -->

CardVerticalGap

You can override the presentation CardVerticalGap metadata value - perhaps to squeeze the gaps between cards:

<!-- md2pptx: cardverticalgap: 0.05 -->

Code

CodeColumns

You can override the presentation CodeColumns metadata value. For example:

<!-- md2pptx: codecolumns: 60 -->

The above changes the CodeColumns value for this and subsequent slides to 60.

FPRatio

You can override the presentation FPRatio (fixed pitch font character height to width ratio) metadata value. For example:

<!-- md2pptx: fpratio: 1.3 -->

The above changes the FPRatio value for this and subsequent slides to 1.3.

CodeForeground

You can override the presentation CodeForeground code slide foreground colour on a slide-by-slide basis:

<!-- md2pptx: codeforeground: 000000 -->

CodeBackground

You can override the presentation CodeBackground code slide background colour on a slide-by-slide basis:

<!-- md2pptx: codebackground: FFFFFF -->

PageTitleSize

You can override the presentation PageTitleSize metadata value - perhaps to allow room for more text in the title of a slide:

<!-- md2pptx: pagetitlesize: 16 -->

BaseTextSize

You can override the presentation BaseTextSize metadata value. For example:

<!-- md2pptx: basetextsize: 16 -->

The above makes the top-level bullets smaller than you would normally see - perhaps to cram in more bullets.

BaseTextDecrement

You can override the presentation BaseTextDecrement metadata value. For example:

<!-- md2pptx: basetextdecrement: 0 -->

The above stops each level of bullets having progressively smaller text.

ContentSplitDirection

You can override the presentation ContentSplitDirection value on a slide-by-slide basis:

<!-- md2pptx: contentsplitdirection: v -->

ContentSplit

You can override the presentation ContentSplit specification on a slide-by-slide basis:

<!-- md2pptx: contentsplit: 1 1 3 -->

IndentSpaces

You can override the presentation IndentSpaces specification on a slide-by-slide basis:

<!-- md2pptx: indentspaces: 4 -->

MarginBase

You can override the presentation MarginBase specification on a slide-by-slide-basis. For example:

<!-- md2pptx: marginbase: 0 -->

You might do this along with a Dynamic NumbersHeight value of 0 to allow something to occupy the whole slide.

NumbersHeight

You can override the presentation NumbersHeight specification on a slide-by-slide-basis. For example:

<!-- md2pptx: numbersheight: 0 -->

You might do this along with a Dynamic MarginBase value of 0 to allow something to occupy the whole slide.

TableMargin

You can override the presentation TableMargin specification on a slide-by-slide-basis:

<!-- md2pptx: tablemargin: 0.25 -->

Modifying The Slide Template

The included template presentation - Martin Template.pptx - is what the author tested with and gives good results. However, you probably want to develop your own template from it.

This section is a basic introduction to the rules of the game for doing so.

Basics

It's best not to change the order of the slides in the slide master view and not to delete any elements. If you have a slide template presentation where the necessary slides are in the wrong order you can override where md2pptx picks its slides from. See the table below for metadata items to specify different template slides i.e override what md2pptx expects. Here's an example:

BlankLayout: 14

In this example, the slide in the template presentation to use for blank slides is number 14, with 0 being the first.

It's probably also not useful to add elements. Take care with moving and resizing elements; It's probably best to experiment to see what effects you get.

Slide Template Sequence

The following table shows how each slide type is created.

Slide Type Origin Metadata
Override		 Non-Title Content
Processing Summary Original slide from Template Metadata: Second Shape
Presentation Title Slide Layout 0 TitleSlideLayout Subtitle: Second Shape
Section Slide Layout 1 SectionSlideLayout Subtitle: Second Shape
Graphic With Title Slide Layout 5 TitleOnlyLayout Graphic: New Shape
Graphic Without Title Slide Layout 6 BlankLayout Graphic: New Shape
Code Slide Layout 5 TitleOnlyLayout Code: New Shape
Content Slide Layout 2 ContentSlideLayout Bulleted List: Second Shape
Table Slide Layout 5 TitleOnlyLayout Table: New Shape
Tasks Slide Layout 2 ContentSlideLayout Bulleted List: Second Shape

Notes:

  1. When looking for a title md2pptx looks first for a title shape and, failing that, uses the first shape. It's the Template Designer's responsibility to size and position it sensibly.
  2. "New Shape" means md2pptx will create a new shape with, hopefully, sensible position and size.
  3. With "Second Shape" it's the Template Designer's responsibility to size and position it sensibly.

Template Slide Types

The following sections give a brief description of each slide type md2pptx builds a presentation from. Your template presentation should have a slide of each type.

The title of each section includes the metadata override for that type of template slide.

Title Slide - TitleSlideLayout

This is for the presentation's overall title. It probably has a title text line half way down the slide - though other designs are possible.

Generally you would use a Heading Level 1 (#) to create such a slide.

Section Slide - SectionSlideLayout

This is for a section within the presentation - and is generally simpler than the presentation title slide. It probably has a title text line half way down the slide - though other designs are possible.

Generally you would use a Heading Level 2 (##) to create such a slide.

Title Only Slide - TitleOnlyLayout

This is used where there will be some content below a title - and md2pptx doesn't use any content that might already be on the slide.

Blank Slide - BlankLayout

This is where md2pptx wants to create a slide without using any content from the template slide.

Content Slide - ContentSlideLayout

This is where md2pptx wants to reuse e.g. a text area. It is expected the template slide will have a title shape.

Deviations From Standard Markdown

While a key aim of the md2pptx project is to keep as closely as possible to standard Markdown (or at any rate Multimarkdown) there are some known incompatibilities. Apart from the fact md2pptx doesn't support all Markdown (or HTML) syntax, the deviations are intended to be useful and optional.

This section lists the known ones so you can make judgments about which deviations to tolerate.

Known deviations are:

  • md2pptx can reference Encapsulated Postscript (EPS) graphics - by converting them to .PNG files. Markdown and HTML can't. See Graphics File References for details of how you specify to md2pptx including graphics of various types.

  • In tables the number of dashes in a column's header is used to denote its relative width. This is not standard Markdown behaviour. See Table Slides for details of md2pptx's Tables support.

  • In tables trailing pipe (|) characters are optional in md2pptx.

  • md2pptx supports inline Taskpaper format. Markdown doesn't. (The use of the Taskpaper - delimiter currently prevents md2pptx from supporting it as a list bullet marker.) See Task List Slides for details of md2pptx's Taskpaper support.