Skip to content

Commit

Permalink
v4.3 Card Slide Graphics
Browse files Browse the repository at this point in the history
  • Loading branch information
@MartinPacker
MartinPacker committed Jan 3, 2024
1 parent 63a66ed commit b05eb85
Show file tree
Hide file tree
Showing 5 changed files with 264 additions and 11 deletions.
75 changes: 72 additions & 3 deletions docs/user-guide.html
View file
Expand Up @@ -1122,7 +1122,11 @@ <h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-o
<li><a href="#multicolumn-table-cells">Multi-Column Table Cells</a></li>
</ul>
</li>
<li><a href="#card-slides">Card Slides</a></li>
<li><a href="#card-slides">Card Slides</a><ul>
<li><a href="#card-titles">Card Titles</a></li>
<li><a href="#card-graphics">Card Graphics</a></li>
</ul>
</li>
<li><a href="#code-slides">Code Slides</a><ul>
<li><a href="#&lt;code&gt;"><code>&lt;code&gt;</code></a></li>
<li><a href="#triple-backticks-()">Triple Backticks (```)</a><ul>
Expand Down Expand Up @@ -1240,6 +1244,9 @@ <h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-o
<li><a href="#card-shape-cardshape">Card Shape - <code>CardShape</code></a></li>
<li><a href="#card-horizontal-gap-cardhorizontalgap">Card Horizontal Gap - <code>CardHorizontalGap</code></a></li>
<li><a href="#card-vertical-gap-cardverticalgap">Card Vertical Gap - <code>CardVerticalGap</code></a></li>
<li><a href="#card-graphic-position-cardgraphicposition">Card Graphic Position - <code>CardGraphicPosition</code></a></li>
<li><a href="#card-graphic-size-cardgraphicsize">Card Graphic Size - <code>CardGraphicSize</code></a></li>
<li><a href="#card-graphic-padding-cardgraphicpadding">Card Graphic Padding - <code>CardGraphicPadding</code></a></li>
</ul>
</li>
<li><a href="#code-metadata">Code Metadata</a><ul>
Expand Down Expand Up @@ -1477,6 +1484,11 @@ <h2 id="change-log">Change Log<a class="headerlink" href="#change-log" title="Pe
</thead>
<tbody>
<tr>
<td align="left">4.3</td>
<td align="right">3&nbsp;January&nbsp;2024</td>
<td align="left">Added card graphics support and <a href="#card-graphic-positioning-cardgraphicposition"><code>CardGraphicPosition</code></a>&comma; <a href="#card-graphic-size-cardgraphicsize"><code>CardGraphicSize</code></a>&comma; and <a href="#card-graphic-padding-cardgraphicpadding"><code>CardGraphicPadding</code></a>.</td>
</tr>
<tr>
<td align="left">4.2.1</td>
<td align="right">28&nbsp;December&nbsp;2023</td>
<td align="left">Made <a href="#specifying-slide-background-images-with-backgroundimage"><code>backgroundImage</code></a> create <strong>real</strong> slide backgrounds.</td>
Expand Down Expand Up @@ -2234,8 +2246,14 @@ <h4 id="multi-column-table-cells">Multi-Column Table Cells<a class="headerlink"
</ol>
<h3 id="card-slides">Card Slides<a class="headerlink" href="#card-slides" title="Permanent link"></a></h3>
<p><a id="card-slides"></a></p>
<p>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 <a href="#bullet-slides">Bullet Slides</a>. In fact this slide type is derivative of the Bullet Slide type.</p>
<p>A card slide can look something like this:</p>
<p>A card slide contains multiple panels - or cards. They come in two flavours:</p>
<ul>
<li>Horizontal - where the cards are next to each other</li>
<li>Vertical - where the cards are one above the other</li>
</ul>
<p>For the rest of this section the assumption is that cards are horizontally arranged. (Vertically-arranged cards are very similar.)</p>
<p>Each card has a title and, below that, the contents are defined using the same syntax as in <a href="#bullet-slides">Bullet Slides</a>. In fact this slide type is derivative of the Bullet Slide type.</p>
<p>A horizontally-arranged card slide can look something like this:</p>
<p><img alt="" src="/Users/martinpacker/md2pptx/docs/CardSlide.png" /></p>
<p>The key features of this slide are:</p>
<ul>
Expand Down Expand Up @@ -2265,13 +2283,38 @@ <h3 id="card-slides">Card Slides<a class="headerlink" href="#card-slides" title=
<li><a href="#card-shape-cardshape">Card Shape</a></li>
<li><a href="#card-horizontal-gap-cardhorizontalgap">Card Horizontal Gap</a></li>
<li><a href="#card-vertical-gap-cardverticalgap">Card Vertical Gap</a></li>
<li><a href="#card-graphic-positioning-cardgraphicposition">Card Graphic Position</a></li>
<li><a href="#card-graphic-size-cardgraphicsize">Card Graphic Size</a></li>
<li><a href="#card-graphic-padding-cardgraphicpadding">Card Graphic Padding</a></li>
</ul>
<p>One example of using a different style is this:</p>
<p><img alt="" src="/Users/martinpacker/md2pptx/docs/cardslide-lines.png" /></p>
<p>Here the card background is invisible but the cards are separated by lines. You achieve this by coding:</p>
<pre><code>CardShape: line
</code></pre>
<p>(See <a href="#card-shape-cardshape">Card Shape</a> for more information.)</p>
<h4 id="card-titles">Card Titles<a class="headerlink" href="#card-titles" title="Permanent link"></a></h4>
<p>In the above examples the card titles are above the cards. You can specify that the card titles are inside the cards, at the top. To do this code:</p>
<pre><code>CardTitlePosition: inside
</code></pre>
<p>(See <a href="#card-title-position-cardtitleposition">Card Title Position</a> for more information.)</p>
<p>You can suppress a title by coding its text value to <code>&amp;nbsp;</code>. If you do this for all the titles on a card slide the space reserved for card titles will be zero. If there are some titles not treated this way the <code>&amp;nbsp;</code>-titled cards will have a gap where the title would have been.</p>
<h4 id="card-graphics">Card Graphics<a class="headerlink" href="#card-graphics" title="Permanent link"></a></h4>
<p>You can add graphics to a card. They can be placed in reserved areas before or after the card bulleted list contents.</p>
<p>Place any graphic declaration between the card&rsquo;s title and the card&rsquo;s contents. For example:</p>
<pre><code>#### Card One

![](block.png)

* Some content for Card One
* And some more content
</code></pre>
<p>As you can see, the image reference is just a standard Markdown one.</p>
<p><strong>Notes:</strong></p>
<ol>
<li>You must code a non-zero value for <code>CardGraphicSize</code> for graphics to be shown. The default is 0.</li>
<li>If a card doesn&rsquo;t have a graphic the bulleted list contents can fill the whole of the card (except for any title inside the card).</li>
</ol>
<h3 id="code-slides">Code Slides<a class="headerlink" href="#code-slides" title="Permanent link"></a></h3>
<p><a id="code-slides"></a></p>
<p>You can create a slide where the body is in a monospace font, without bullets, in a number of different ways:</p>
Expand Down Expand Up @@ -3506,6 +3549,32 @@ <h5 id="card-vertical-gap-cardverticalgap">Card Vertical Gap - <code>CardVertica
</code></pre>
<p>The default is 0.1 inches.</p>
<p>You can override this on a slide-by-slide basis with <a href="#dynamic-cardverticalgap">Dynamic Vertical Gap</a>.</p>
<p><a id="card-graphic-positioning-cardgraphicposition"></a></p>
<h5 id="card-graphic-position-cardgraphicposition">Card Graphic Position - <code>CardGraphicPosition</code><a class="headerlink" href="#card-graphic-position-cardgraphicposition" title="Permanent link"></a></h5>
<p>You can specify whether any graphic appears before or after the bulleted list contents of the card:</p>
<pre><code>cardGraphicPosition: after
</code></pre>
<p>causes the graphic to appear after the bulleted list.</p>
<p><code>before</code> (which is the default) causes the graphic to appear before the bulleted list.</p>
<p><strong>Notes:</strong></p>
<ol>
<li>The values <code>before</code> and <code>after</code> are used because they work in both horizontal and vertical layouts.</li>
<li>If <code>before</code> is specified, in horizontal layout, the graphics appear below any titles.</li>
<li>You can cause graphics to replace text titles by specifying <code>&amp;nbsp;</code> for all the titles - and specifying graphics instead.</li>
</ol>
<p><a id="card-graphic-size-cardgraphicsize"></a></p>
<h5 id="card-graphic-size-cardgraphicsize">Card Graphic Size - <code>CardGraphicSize</code><a class="headerlink" href="#card-graphic-size-cardgraphicsize" title="Permanent link"></a></h5>
<p>If you want graphics to appear in cards you must specify a non-zero value of <code>CardGraphicSize</code>. For example:</p>
<pre><code>cardGraphicSize: 0.75
</code></pre>
<p>would cause the graphics to be scaled to fit into a 0.75 inch square.</p>
<p>The default is <code>0</code>, that is no graphics.</p>
<p><a id="card-graphic-padding-cardgraphicpadding"></a></p>
<h5 id="card-graphic-padding-cardgraphicpadding">Card Graphic Padding - <code>CardGraphicPadding</code><a class="headerlink" href="#card-graphic-padding-cardgraphicpadding" title="Permanent link"></a></h5>
<p>You can specify space around the graphic on a card. For example:</p>
<pre><code>cardGraphicPadding: 0.5
</code></pre>
<p>will leave a space of 0.5 inches around the graphic. The default is <code>0.1</code>, leaving a 0.1 inch pad around the graphics.</p>
<p><a id="code-metadata"></></p>
<h4 id="code-metadata">Code Metadata<a class="headerlink" href="#code-metadata" title="Permanent link"></a></h4>
<p>You can adjust how code slides display their content.</p>
Expand Down
9 changes: 7 additions & 2 deletions docs/user-guide.log
View file
Expand Up @@ -5,8 +5,8 @@ mdpre Markdown Preprocessor v0.6.7 (17 December, 2023)
Def mdpre_date = 17 December, 2023
Def mdpre_level = 0.6.7
Def userid = martinpacker
Def time = 11&colon;55
Def date = 28 December&comma; 2023
Def time = 19&colon;43
Def date = 3 January&comma; 2024
Def TOC = Table Of Contents
Def md = Markdown
Def pp = Powerpoint
Expand Down Expand Up @@ -43,6 +43,8 @@ CSV Stop
..... ..... ..... Special Case: One Graphic Above Another
..... ..... ..... Multi-Column Table Cells
..... ..... Card Slides
..... ..... ..... Card Titles
..... ..... ..... Card Graphics
..... ..... Code Slides
..... ..... ..... `<code>`
..... ..... ..... Triple Backticks (```)
Expand Down Expand Up @@ -137,6 +139,9 @@ CSV Stop
..... ..... ..... ..... Card Shape - `CardShape`
..... ..... ..... ..... Card Horizontal Gap - `CardHorizontalGap`
..... ..... ..... ..... Card Vertical Gap - `CardVerticalGap`
..... ..... ..... ..... Card Graphic Position - `CardGraphicPosition`
..... ..... ..... ..... Card Graphic Size - `CardGraphicSize`
..... ..... ..... ..... Card Graphic Padding - `CardGraphicPadding`
..... ..... ..... Code Metadata
..... ..... ..... ..... Code Column Count - `CodeColumns`
..... ..... ..... ..... Fixed Pitch Height To Width Ratio - `FPRatio`
Expand Down
90 changes: 88 additions & 2 deletions docs/user-guide.md
View file
Expand Up @@ -36,6 +36,8 @@ As you can see in the [change log](#change-log), md2pptx is frequently updated -
* [Special Case: One Graphic Above Another](#special-case-one-graphic-above-another)
* [Multi-Column Table Cells](#multicolumn-table-cells)
* [Card Slides](#card-slides)
* [Card Titles](#card-titles)
* [Card Graphics](#card-graphics)
* [Code Slides](#code-slides)
* [`<code>`](#<code>)
* [Triple Backticks (```)](#triple-backticks-())
Expand Down Expand Up @@ -125,6 +127,9 @@ As you can see in the [change log](#change-log), md2pptx is frequently updated -
* [Card Shape - `CardShape`](#card-shape-cardshape)
* [Card Horizontal Gap - `CardHorizontalGap`](#card-horizontal-gap-cardhorizontalgap)
* [Card Vertical Gap - `CardVerticalGap`](#card-vertical-gap-cardverticalgap)
* [Card Graphic Position - `CardGraphicPosition`](#card-graphic-position-cardgraphicposition)
* [Card Graphic Size - `CardGraphicSize`](#card-graphic-size-cardgraphicsize)
* [Card Graphic Padding - `CardGraphicPadding`](#card-graphic-padding-cardgraphicpadding)
* [Code Metadata](#code-metadata)
* [Code Column Count - `CodeColumns`](#code-column-count-codecolumns)
* [Fixed Pitch Height To Width Ratio - `FPRatio`](#fixed-pitch-height-to-width-ratio-fpratio)
Expand Down Expand Up @@ -343,6 +348,7 @@ To quote from the python-pptx license statement:

|Level|Date|What|
|:-|-:|:-|
|4.3|3&nbsp;January&nbsp;2024|Added card graphics support and [`CardGraphicPosition`](#card-graphic-positioning-cardgraphicposition)&comma; [`CardGraphicSize`](#card-graphic-size-cardgraphicsize)&comma; and [`CardGraphicPadding`](#card-graphic-padding-cardgraphicpadding).|
|4.2.1|28&nbsp;December&nbsp;2023|Made [`backgroundImage`](#specifying-slide-background-images-with-backgroundimage) create **real** slide backgrounds.|
|4.2|27&nbsp;December&nbsp;2023|Added background image support using [`backgroundImage`](#specifying-slide-background-images-with-backgroundimage).|
|4.1.2|11&nbsp;July&nbsp;2023|Fixed two bugs: Using `<sub>` &amp; `<sup>` causes a crash. Also [Card Slides](#card-slides) cause a crash.|
Expand Down Expand Up @@ -854,9 +860,16 @@ In this example
### Card Slides
<a id="card-slides"></a>

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](#bullet-slides). In fact this slide type is derivative of the Bullet Slide type.
A card slide contains multiple panels - or cards. They come in two flavours:

A card slide can look something like this:
* Horizontal - where the cards are next to each other
* Vertical - where the cards are one above the other

For the rest of this section the assumption is that cards are horizontally arranged. (Vertically-arranged cards are very similar.)

Each card has a title and, below that, the contents are defined using the same syntax as in [Bullet Slides](#bullet-slides). In fact this slide type is derivative of the Bullet Slide type.

A horizontally-arranged card slide can look something like this:

![](CardSlide.png)

Expand Down Expand Up @@ -887,6 +900,9 @@ In the above example there has been a small amount of tweaking of the format, us
* [Card Shape](#card-shape-cardshape)
* [Card Horizontal Gap](#card-horizontal-gap-cardhorizontalgap)
* [Card Vertical Gap](#card-vertical-gap-cardverticalgap)
* [Card Graphic Position](#card-graphic-positioning-cardgraphicposition)
* [Card Graphic Size](#card-graphic-size-cardgraphicsize)
* [Card Graphic Padding](#card-graphic-padding-cardgraphicpadding)

One example of using a different style is this:

Expand All @@ -898,6 +914,38 @@ Here the card background is invisible but the cards are separated by lines. You

(See [Card Shape](#card-shape-cardshape) for more information.)


#### Card Titles

In the above examples the card titles are above the cards. You can specify that the card titles are inside the cards, at the top. To do this code:

CardTitlePosition: inside

(See [Card Title Position](#card-title-position-cardtitleposition) for more information.)

You can suppress a title by coding its text value to `&nbsp;`. If you do this for all the titles on a card slide the space reserved for card titles will be zero. If there are some titles not treated this way the `&nbsp;`-titled cards will have a gap where the title would have been.

#### Card Graphics

You can add graphics to a card. They can be placed in reserved areas before or after the card bulleted list contents.

Place any graphic declaration between the card's title and the card's contents. For example:

#### Card One

![](block.png)

* Some content for Card One
* And some more content

As you can see, the image reference is just a standard Markdown one.

**Notes:**

1. You must code a non-zero value for `CardGraphicSize` for graphics to be shown. The default is 0.
2. If a card doesn't have a graphic the bulleted list contents can fill the whole of the card (except for any title inside the card).


### Code Slides
<a id="code-slides"></a>

Expand Down Expand Up @@ -2343,6 +2391,44 @@ The default is 0.1 inches.

You can override this on a slide-by-slide basis with [Dynamic Vertical Gap](#dynamic-cardverticalgap).


<a id="card-graphic-positioning-cardgraphicposition"></a>
##### Card Graphic Position - `CardGraphicPosition`

You can specify whether any graphic appears before or after the bulleted list contents of the card:

cardGraphicPosition: after

causes the graphic to appear after the bulleted list.

`before` (which is the default) causes the graphic to appear before the bulleted list.

**Notes:**

1. The values `before` and `after` are used because they work in both horizontal and vertical layouts.
1. If `before` is specified, in horizontal layout, the graphics appear below any titles.
1. You can cause graphics to replace text titles by specifying `&nbsp;` for all the titles - and specifying graphics instead.

<a id="card-graphic-size-cardgraphicsize"></a>
##### Card Graphic Size - `CardGraphicSize`

If you want graphics to appear in cards you must specify a non-zero value of `CardGraphicSize`. For example:

cardGraphicSize: 0.75

would cause the graphics to be scaled to fit into a 0.75 inch square.

The default is `0`, that is no graphics.

<a id="card-graphic-padding-cardgraphicpadding"></a>
##### Card Graphic Padding - `CardGraphicPadding`

You can specify space around the graphic on a card. For example:

cardGraphicPadding: 0.5

will leave a space of 0.5 inches around the graphic. The default is `0.1`, leaving a 0.1 inch pad around the graphics.

<a id="code-metadata"></>
#### Code Metadata

Expand Down

0 comments on commit b05eb85

Please sign in to comment.