Skip to content

Commit

Permalink
v3.7
Browse files Browse the repository at this point in the history
  • Loading branch information
@MartinPacker
MartinPacker committed Mar 26, 2023
1 parent 6ba42c3 commit ae70d27
Show file tree
Hide file tree
Showing 5 changed files with 218 additions and 76 deletions.
4 changes: 2 additions & 2 deletions md2pptx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,8 @@ except:
have_graphviz = False


md2pptx_level = "3.6+"
md2pptx_date = "25 March, 2023"
md2pptx_level = "3.7"
md2pptx_date = "26 March, 2023"

namespaceURL = {
"mc" : "http://schemas.openxmlformats.org/markup-compatibility/2006",
Expand Down
86 changes: 63 additions & 23 deletions user-guide.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1068,6 +1068,7 @@
</style><title>user-guide</title></head><body><article class="markdown-body"><h1 id="markdown-to-powerpoint-user-guide">Markdown To Powerpoint User Guide<a class="headerlink" href="#markdown-to-powerpoint-user-guide" title="Permanent link"></a></h1>
<p>This document describes the md2pptx Markdown preprocessor, which turns Markdown text into a Powerpoint presentation (whether .pptx or <a href="#invoking-a-vba-macro">.pptm</a>).</p>
<p>In this document we&rsquo;ll refer to it as &ldquo;md2pptx&rdquo;, pronounced &ldquo;em dee to pee pee tee ex&rdquo;.</p>
<p>As you can see in the <a href="#change-log">change log</a>, md2pptx is frequently updated - both for bug fixes and enhancements.</p>
<h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-of-contents" title="Permanent link"></a></h3>
<ul>
<li><a href="#why-md2pptx">Why md2pptx?</a><ul>
Expand Down Expand Up @@ -1167,6 +1168,11 @@ <h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-o
<li><a href="#controlling-the-presentation-with-metadata">Controlling The Presentation With Metadata</a><ul>
<li><a href="#specifying-metadata">Specifying Metadata</a><ul>
<li><a href="#processing-summary">Processing Summary</a></li>
<li><a href="#specifying-colours">Specifying Colours</a><ul>
<li><a href="#theme-colours">Theme Colours</a></li>
<li><a href="#rgb-colours">RGB Colours</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#metadata-keys">Metadata Keys</a><ul>
Expand Down Expand Up @@ -1211,6 +1217,7 @@ <h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-o
<li><a href="#card-border-width-cardborderwidth">Card Border Width - <code>CardBorderWidth</code></a></li>
<li><a href="#card-title-size-cardtitlesize">Card Title Size - <code>CardTitleSize</code></a></li>
<li><a href="#card-title-colour-cardtitlecolour">Card Title Colour - <code>cardTitleColour</code></a></li>
<li><a href="#card-divider-colour-carddividercolour">Card Divider Colour - <code>cardDividerColour</code></a></li>
<li><a href="#card-shadow-cardshadow">Card Shadow - <code>CardShadow</code></a></li>
<li><a href="#card-size-cardpercent">Card Size - <code>CardPercent</code></a></li>
<li><a href="#card-layout-direction-cardlayout">Card Layout Direction - <code>CardLayout</code></a></li>
Expand Down Expand Up @@ -1431,6 +1438,11 @@ <h2 id="change-log">Change Log<a class="headerlink" href="#change-log" title="Pe
</thead>
<tbody>
<tr>
<td align="left">3.7</td>
<td align="right">26&nbsp;March&nbsp;2023</td>
<td align="left">Added <a href="#card-divider-colour-carddividercolour"><code>cardDividerColour</code></a>. Most colours now RGB or Theme Colour (documented in <a href="#specifying-colours">Specifying Colours</a>).</td>
</tr>
<tr>
<td align="left">3.6</td>
<td align="right">18&nbsp;March&nbsp;2023</td>
<td align="left">Added <a href="#card-title-colour-cardtitlecolour"><code>cardTitleColour</code></a> &amp; <code>line</code> for <a href="#card-shape-cardshape"><code>cardshape</code></a>. Allow multiple colours for <a href="#card-background-colour-cardcolour"><code>cardColour</code></a>.</td>
Expand Down Expand Up @@ -2174,6 +2186,7 @@ <h3 id="card-slides">Card Slides<a class="headerlink" href="#card-slides" title=
<li><a href="#card-border-width-cardborderwidth">Card Border Width</a></li>
<li><a href="#card-title-size-cardtitlesize">Card Title Font Size</a></li>
<li><a href="#card-title-colour-cardtitlecolour">Card Title Colour</a></li>
<li><a href="#card-divider-colour-carddividercolour">Card Divider Colour</a></li>
<li><a href="#card-shadow-cardshadow">Card Shadow</a></li>
<li><a href="#card-size-cardpercent">Card Size</a></li>
<li><a href="#card-layout-direction-cardlayout">Card Layout Direction</a></li>
Expand Down Expand Up @@ -2855,6 +2868,50 @@ <h4 id="processing-summary">Processing Summary<a class="headerlink" href="#proce
<li>You can suppress <code>style.</code> metadata items by specifying the metadata item <code>hideMetadata: style</code>. In the md2pptx developer&rsquo;s experience <code>style.</code> metadata items can become numerous and could obscure more important items in the Processing Summary slide. The default is not to hide such items.</li>
<li>Before the metadata table is created md2pptx will remove all but the title item in this slide. The one type of item that won&rsquo;t be removed is any Action Buttons. See <a href="#sample-macro-to-remove-the-first-slide">Sample Macro To Remove The First Slide</a> for an example of where these might be useful.</li>
</ol>
<h4 id="specifying-colours">Specifying Colours<a class="headerlink" href="#specifying-colours" title="Permanent link"></a></h4>
<p><a id="specifying-colours"></a></p>
<p>In most places where you specify colours they can be of one of two forms:</p>
<ul>
<li>A theme colour</li>
<li>An RGB value</li>
</ul>
<h5 id="theme-colours">Theme Colours<a class="headerlink" href="#theme-colours" title="Permanent link"></a></h5>
<p><a id="theme-colours"></a></p>
<p>Powerpoint themes have named theme colours. The names you can use with md2pptx are:</p>
<ul>
<li>NONE</li>
<li>ACCENT 1</li>
<li>ACCENT 2</li>
<li>ACCENT 3</li>
<li>ACCENT 4</li>
<li>ACCENT 5</li>
<li>ACCENT 6</li>
<li>BACKGROUND 1</li>
<li>BACKGROUND 2</li>
<li>DARK 1</li>
<li>DARK 2</li>
<li>FOLLOWED HYPERLINK</li>
<li>HYPERLINK</li>
<li>LIGHT 1</li>
<li>LIGHT 2</li>
<li>TEXT 1</li>
<li>TEXT 2</li>
<li>MIXED</li>
</ul>
<p>As you can probably guess, these are standard values for python-pptx and, ultimately, PowerPoint.</p>
<p>Here is an example:</p>
<pre><code>BoldColour: ACCENT 1
</code></pre>
<p>This will give you more consistent colouring than <a href="#rgb-colours">RGB Colours</a>.</p>
<p><strong>Note:</strong> For the values you can use any capitalisation you like (or none). e.g. <code>ItalicColor: dark 1</code>.</p>
<h5 id="rgb-colours">RGB Colours<a class="headerlink" href="#rgb-colours" title="Permanent link"></a></h5>
<p><a id="rgb-colours"></a></p>
<p>RGB stands for &ldquo;Red, Green, and Blue&rdquo;. You specify RGB values as 6 hexadecimal digits. For example:</p>
<pre><code>ItalicColour: #FF0000
</code></pre>
<p>Each pair of hexadecimal digits represents Red, Green, and Blue, respectively. Each is a hexadecimal encoding of 0-255, with 0 being &ldquo;none of this colour&rdquo; and 255 being &ldquo;saturated in this colour&rdquo;.</p>
<p>This will give you more precise colouring than <a href="#theme-colours">Theme Colours</a>.</p>
<p><strong>Note:</strong> You must include the octothorpe (<code>#</code>) before the hexadecimal value.</p>
<h3 id="metadata-keys">Metadata Keys<a class="headerlink" href="#metadata-keys" title="Permanent link"></a></h3>
<p><a id="metadata-keys"></a></p>
<p>The following sections describe each of the metadata keys.</p>
Expand Down Expand Up @@ -3039,29 +3096,6 @@ <h4 id="specifying-bold-and-italic-text-colour-with-boldcolour-and-italiccolour"
<pre><code>BoldColour: ACCENT 1
</code></pre>
<p>Will cause text marked like so <code>**I am bold**</code> to be rendered in the presentation&rsquo;s smartmaster&rsquo;s &ldquo;Accent 1&rdquo; colour.</p>
<p>The values you can use for <code>BoldColour</code> and <code>ItalicColour</code> are:</p>
<ul>
<li>NONE</li>
<li>ACCENT 1</li>
<li>ACCENT 2</li>
<li>ACCENT 3</li>
<li>ACCENT 4</li>
<li>ACCENT 5</li>
<li>ACCENT 6</li>
<li>BACKGROUND 1</li>
<li>BACKGROUND 2</li>
<li>DARK 1</li>
<li>DARK 2</li>
<li>FOLLOWED HYPERLINK</li>
<li>HYPERLINK</li>
<li>LIGHT 1</li>
<li>LIGHT 2</li>
<li>TEXT 1</li>
<li>TEXT 2</li>
<li>MIXED</li>
</ul>
<p>As you can probably guess, these are standard values for python-pptx and, ultimately, PowerPoint.</p>
<p><strong>Note:</strong> For the values you can use any capitalisation you like (or none). e.g. <code>ItalicColor: dark 1</code>.</p>
<h4 id="specifying-bold-and-italic-text-effects-with-boldbold-and-italicitalic">Specifying Bold And Italic Text Effects With <code>BoldBold</code> And <code>ItalicItalic</code><a class="headerlink" href="#specifying-bold-and-italic-text-effects-with-boldbold-and-italicitalic" title="Permanent link"></a></h4>
<p><a id="specifying-bold-and-italic-text-effects-with-boldbold-and-italicitalic"></a></p>
<p>You can modify how md2pptx formats bold and italic text.</p>
Expand Down Expand Up @@ -3244,6 +3278,12 @@ <h5 id="card-title-colour-cardtitlecolour">Card Title Colour - <code>cardTitleCo
<pre><code>CardTitleColour: DARK 1
</code></pre>
<p>would set the cards&rsquo; titles to the theme&rsquo;s &ldquo;DARK 1&rdquo; colour.</p>
<h5 id="card-divider-colour-carddividercolour">Card Divider Colour - <code>cardDividerColour</code><a class="headerlink" href="#card-divider-colour-carddividercolour" title="Permanent link"></a></h5>
<p><a id="card-divider-colour-carddividercolour"></a></p>
<p>You can specify the colour of lines between cards - if the <code>line</code> style is chosen. For example:</p>
<pre><code>CardLineColour: ACCENT 1
</code></pre>
<p>would set the lines between cards to the theme&rsquo;s &ldquo;ACCENT 1&rdquo; colour.</p>
<h5 id="card-shadow-cardshadow">Card Shadow - <code>CardShadow</code><a class="headerlink" href="#card-shadow-cardshadow" title="Permanent link"></a></h5>
<p><a id="card-shadow-cardshadow"></a></p>
<p>You can specify whether a card has a shadow - using <code>CardShadow</code>. For example:</p>
Expand Down
8 changes: 6 additions & 2 deletions user-guide.log
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ mdpre Markdown Preprocessor v0.6.5 (17 February, 2023)
Def mdpre_date = 17 February, 2023
Def mdpre_level = 0.6.5
Def userid = martinpacker
Def time = 14&colon;13
Def date = 18 March&comma; 2023
Def time = 13&colon;59
Def date = 26 March&comma; 2023
Def TOC = Table Of Contents
Def md = Markdown
Def pp = Powerpoint
Expand Down Expand Up @@ -83,6 +83,9 @@ CSV Stop
..... Controlling The Presentation With Metadata
..... ..... Specifying Metadata
..... ..... ..... Processing Summary
..... ..... ..... Specifying Colours
..... ..... ..... ..... Theme Colours
..... ..... ..... ..... RGB Colours
..... ..... Metadata Keys
..... ..... ..... Title And Subtitle Font Sizes And Alignment
..... ..... ..... ..... Page Title Size - `pageTitleSize`
Expand Down Expand Up @@ -121,6 +124,7 @@ CSV Stop
..... ..... ..... ..... Card Border Width - `CardBorderWidth`
..... ..... ..... ..... Card Title Size - `CardTitleSize`
..... ..... ..... ..... Card Title Colour - `cardTitleColour`
..... ..... ..... ..... Card Divider Colour - `cardDividerColour`
..... ..... ..... ..... Card Shadow - `CardShadow`
..... ..... ..... ..... Card Size - `CardPercent`
..... ..... ..... ..... Card Layout Direction - `CardLayout`
Expand Down
96 changes: 72 additions & 24 deletions user-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ This document describes the md2pptx Markdown preprocessor, which turns Markdown

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

As you can see in the [change log](#change-log), md2pptx is frequently updated - both for bug fixes and enhancements.

### Table Of Contents

* [Why md2pptx?](#why-md2pptx)
Expand Down Expand Up @@ -70,6 +72,9 @@ In this document we'll refer to it as "md2pptx", pronounced "em dee to pee pee t
* [Controlling The Presentation With Metadata](#controlling-the-presentation-with-metadata)
* [Specifying Metadata](#specifying-metadata)
* [Processing Summary](#processing-summary)
* [Specifying Colours](#specifying-colours)
* [Theme Colours](#theme-colours)
* [RGB Colours](#rgb-colours)
* [Metadata Keys](#metadata-keys)
* [Title And Subtitle Font Sizes And Alignment](#title-and-subtitle-font-sizes-and-alignment)
* [Page Title Size - `pageTitleSize`](#page-title-size-pagetitlesize)
Expand Down Expand Up @@ -108,6 +113,7 @@ In this document we'll refer to it as "md2pptx", pronounced "em dee to pee pee t
* [Card Border Width - `CardBorderWidth`](#card-border-width-cardborderwidth)
* [Card Title Size - `CardTitleSize`](#card-title-size-cardtitlesize)
* [Card Title Colour - `cardTitleColour`](#card-title-colour-cardtitlecolour)
* [Card Divider Colour - `cardDividerColour`](#card-divider-colour-carddividercolour)
* [Card Shadow - `CardShadow`](#card-shadow-cardshadow)
* [Card Size - `CardPercent`](#card-size-cardpercent)
* [Card Layout Direction - `CardLayout`](#card-layout-direction-cardlayout)
Expand Down Expand Up @@ -313,6 +319,7 @@ To quote from the python-pptx license statement:

|Level|Date|What|
|:-|-:|:-|
|3.7|26&nbsp;March&nbsp;2023|Added [`cardDividerColour`](#card-divider-colour-carddividercolour). Most colours now RGB or Theme Colour (documented in [Specifying Colours](#specifying-colours)).|
|3.6|18&nbsp;March&nbsp;2023|Added [`cardTitleColour`](#card-title-colour-cardtitlecolour) &amp; `line` for [`cardshape`](#card-shape-cardshape). Allow multiple colours for [`cardColour`](#card-background-colour-cardcolour).|
|3.5.2|14&nbsp;March&nbsp;2023|Added [`pageTitleAlign`](#page-title-alignment-pagetitlealign) - for content page title alignment.|
|3.5.1|3&nbsp;March&nbsp;2023|[`pageSubtitleSize`](#page-subtitle-size-pagesubtitlesize) supports `same` meaning "same font size as first line".|
Expand Down Expand Up @@ -840,6 +847,7 @@ In the above example there has been a small amount of tweaking of the format, us
* [Card Border Width](#card-border-width-cardborderwidth)
* [Card Title Font Size](#card-title-size-cardtitlesize)
* [Card Title Colour](#card-title-colour-cardtitlecolour)
* [Card Divider Colour](#card-divider-colour-carddividercolour)
* [Card Shadow](#card-shadow-cardshadow)
* [Card Size](#card-size-cardpercent)
* [Card Layout Direction](#card-layout-direction-cardlayout)
Expand Down Expand Up @@ -1527,6 +1535,61 @@ As described in [Creating Slides](#creating-slides), md2pptx will populate the f
1. 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.
1. Before the metadata table is created md2pptx will remove all but the title item in this slide. The one type of item that won't be removed is any Action Buttons. See [Sample Macro To Remove The First Slide](#sample-macro-to-remove-the-first-slide) for an example of where these might be useful.

#### Specifying Colours
<a id="specifying-colours"></a>

In most places where you specify colours they can be of one of two forms:

* A theme colour
* An RGB value

##### Theme Colours
<a id="theme-colours"></a>

Powerpoint themes have named theme colours. The names you can use with md2pptx 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.

Here is an example:

BoldColour: ACCENT 1

This will give you more consistent colouring than [RGB Colours](#rgb-colours).

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

##### RGB Colours
<a id="rgb-colours"></a>

RGB stands for "Red, Green, and Blue". You specify RGB values as 6 hexadecimal digits. For example:

ItalicColour: #FF0000

Each pair of hexadecimal digits represents Red, Green, and Blue, respectively. Each is a hexadecimal encoding of 0-255, with 0 being "none of this colour" and 255 being "saturated in this colour".

This will give you more precise colouring than [Theme Colours](#theme-colours).

**Note:** You must include the octothorpe (`#`) before the hexadecimal value.

### Metadata Keys
<a id="metadata-keys"></a>

Expand Down Expand Up @@ -1798,30 +1861,6 @@ For example:

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`
<a id="specifying-bold-and-italic-text-effects-with-boldbold-and-italicitalic"></a>
Expand Down Expand Up @@ -2094,6 +2133,15 @@ You can specify the colour of cards' titles with `cardTitleColour`. For example:

would set the cards' titles to the theme's "DARK 1" colour.

##### Card Divider Colour - `cardDividerColour`
<a id="card-divider-colour-carddividercolour"></a>

You can specify the colour of lines between cards - if the `line` style is chosen. For example:

CardLineColour: ACCENT 1

would set the lines between cards to the theme's "ACCENT 1" colour.

##### Card Shadow - `CardShadow`
<a id="card-shadow-cardshadow"></a>

Expand Down
Loading

0 comments on commit ae70d27

Please sign in to comment.