From d3ed6d5c4c2ab6b180fa512f240b3b54e0385b59 Mon Sep 17 00:00:00 2001
From: MartinPacker <martin_packer@uk.ibm.com>
Date: Sat, 25 Feb 2023 16:53:03 +0000
Subject: [PATCH] v3.5.1 PageSubtitleSize

---
 md2pptx         |   2 +-
 user-guide.html |  45 +++++++++++++++---
 user-guide.log  |   6 ++-
 user-guide.md   |  54 ++++++++++++++++++---
 user-guide.mdp  | 122 +++++++++++++++++++++++++++++++++++++-----------
 5 files changed, 185 insertions(+), 44 deletions(-)

diff --git a/md2pptx b/md2pptx
index 7773b4d..6d2e976 100755
--- a/md2pptx
+++ b/md2pptx
@@ -75,7 +75,7 @@ except:
 	have_graphviz = False
 
 
-md2pptx_level = "3.5+"
+md2pptx_level = "3.5.1"
 md2pptx_date = "25 February, 2023"
 
 namespaceURL = {
diff --git a/user-guide.html b/user-guide.html
index d24a2a4..5036118 100644
--- a/user-guide.html
+++ b/user-guide.html
@@ -1172,6 +1172,7 @@ <h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-o
 <li><a href="#metadata-keys">Metadata Keys</a><ul>
 <li><a href="#title-and-subtitle-font-sizes">Title And Subtitle Font Sizes</a><ul>
 <li><a href="#page-title-size-pagetitlesize">Page Title Size - <code>pageTitleSize</code></a></li>
+<li><a href="#page-subtitle-size-pagesubtitlesize">Page Subtitle Size - <code>pageSubtitleSize</code></a></li>
 <li><a href="#section-title-size-sectiontitlesize">Section Title Size - <code>sectionTitleSize</code></a></li>
 <li><a href="#section-subtitle-size-sectionsubtitlesize">Section Subtitle Size - <code>sectionSubtitleSize</code></a></li>
 <li><a href="#presentation-title-size-prestitlesize">Presentation Title Size - <code>presTitleSize</code></a></li>
@@ -1291,6 +1292,7 @@ <h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-o
 </ul>
 </li>
 <li><a href="#pagetitlesize"><code>PageTitleSize</code></a></li>
+<li><a href="#pagesubtitlesize"><code>PageSubtitleSize</code></a></li>
 <li><a href="#basetextsize"><code>BaseTextSize</code></a></li>
 <li><a href="#basetextdecrement"><code>BaseTextDecrement</code></a></li>
 <li><a href="#contentsplitdirection"><code>ContentSplitDirection</code></a></li>
@@ -1344,7 +1346,7 @@ <h2 id="why-md2pptx">Why md2pptx?<a class="headerlink" href="#why-md2pptx" title
 <li>Markdown is compact; The files are tiny.</li>
 <li>Markdown is used in popular sites, such as <a href="https://github.com">Github</a>.</li>
 </ul>
-<p>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.</p>
+<p>Every piece of text you use to create a Powerpoint presentation with md2pptx is valid Markdown - <a href="#deviations-from-standard-markdown">with very few exceptions</a>. 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.</p>
 <p>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&rsquo;t even run. All you need is to be able to run Python 3 and install python-pptx.</p>
 <h3 id="a-real-world-use-case">A Real World Use Case<a class="headerlink" href="#a-real-world-use-case" title="Permanent link"></a></h3>
 <p>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.</p>
@@ -1427,6 +1429,11 @@ <h2 id="change-log">Change Log<a class="headerlink" href="#change-log" title="Pe
 </thead>
 <tbody>
 <tr>
+<td align="left">3.5.1</td>
+<td align="right">25&nbsp;February&nbsp;2023</td>
+<td align="left">Added support for separately scaling second and subsequent slide title lines - with <a href="#page-subtitle-size-pagesubtitlesize"><code>pageSubtitleSize</code></a>.</td>
+</tr>
+<tr>
 <td align="left">3.5</td>
 <td align="right">18&nbsp;February&nbsp;2023</td>
 <td align="left">Added support for GraphViz .dot file rendering within triple backticks</td>
@@ -1886,7 +1893,6 @@ <h3 id="presentation-section-slides">Presentation Section Slides<a class="header
 <h3 id="bullet-slides">Bullet Slides<a class="headerlink" href="#bullet-slides" title="Permanent link"></a></h3>
 <p><a id="bullet-slides"></a></p>
 <p>Bullet slides use Markdown bulleted lists, which can be nested. This example shows two levels of nesting.</p>
-<p>The title of the slide is defined by coding a Markdown Heading Level 3.</p>
 <pre><code>### This Is A Bullet Slide
 
 * Bullet One
@@ -1895,11 +1901,13 @@ <h3 id="bullet-slides">Bullet Slides<a class="headerlink" href="#bullet-slides"
 * Bullet Two
 * Bullet Three
 </code></pre>
+<p>The title of the slide is defined by coding a Markdown Heading Level 3 (<code>###</code>).</p>
+<p><strong>Note:</strong> You can allow the title to spill onto a second line but it is better to break titles up using <code>&lt;br/&gt;</code>. Doing so enables md2pptx to layout slide contents below the title better. It also allows you to specify a different (probably) smaller font size for the second and subsequent lines of the title.</p>
 <p>Bulleted list items are introduced by an asterisk.</p>
-<p><strong>NOTE:</strong> Some dialects of Markdown allow other bullet markers but md2pptx doesn&rsquo;t. You can be sure by coding <code>*</code> you have valid Markdown that md2pptx can also process correctly. For an explanation of why you have to stick to <code>*</code> see <a href="#task-list-slides">here</a>.</p>
+<p><strong>Note:</strong> Some dialects of Markdown allow other bullet markers but md2pptx doesn&rsquo;t. You can be sure by coding <code>*</code> you have valid Markdown that md2pptx can also process correctly. For an explanation of why you have to stick to <code>*</code> see <a href="#task-list-slides">here</a>.</p>
 <p>To nest bullets use a tab character or 2 spaces to indent the sub-bullets. md2pptx doesn&rsquo;t have a limit on the level of nesting but Powerpoint probably does.</p>
 <p>Terminate the bulleted list slide with a blank line.</p>
-<p><strong>NOTE:</strong> You can alter the number of spaces that represent each level of indenting. See <a href="#specifying-how-many-spaces-represent-an-indentation-level-with-indentspaces">Specifying How Many Spaces Represent An Indentation Level With <code>IndentSpaces</code></a>. If you use tabs they will be converted to the the appropriate number of spaces internally.</p>
+<p><strong>Note:</strong> You can alter the number of spaces that represent each level of indenting. See <a href="#specifying-how-many-spaces-represent-an-indentation-level-with-indentspaces">Specifying How Many Spaces Represent An Indentation Level With <code>IndentSpaces</code></a>. If you use tabs they will be converted to the the appropriate number of spaces internally.</p>
 <h4 id="numbered-list-items">Numbered List Items<a class="headerlink" href="#numbered-list-items" title="Permanent link"></a></h4>
 <p><a id="numbered-items"></a></p>
 <p>Within a bullet slide you can have numbered items. Here is an example of a slide with mixed numbers and bullets:</p>
@@ -2466,7 +2474,7 @@ <h2 id="html-comments">HTML Comments<a class="headerlink" href="#html-comments"
 <p>End the last line with <code>--&gt;</code>.</p>
 <p>md2pptx will throw away HTML comments, rather than adding them to the output file.</p>
 <p>The one exception is the use of <a href="#dynamic-metadata">Dynamic Metadata</a>. md2pptx will honour these.</p>
-<p><strong>NOTE:</strong> Other Markdown processors will copy the comment into the output file. Put nothing in the comments that is sensitive.</p>
+<p><strong>Note:</strong> Other Markdown processors will copy the comment into the output file. Put nothing in the comments that is sensitive.</p>
 <h2 id="special-text-formatting">Special Text Formatting<a class="headerlink" href="#special-text-formatting" title="Permanent link"></a></h2>
 <p><a id="special-text-formatting"></a></p>
 <p>Markdown and md2pptx allow additional ways of formatting text. The syntax md2pptx supports is a subset of what many Markdown processors allow.</p>
@@ -2827,14 +2835,34 @@ <h3 id="metadata-keys">Metadata Keys<a class="headerlink" href="#metadata-keys"
 <p><a id="metadata-keys"></a></p>
 <p>The following sections describe each of the metadata keys.</p>
 <h4 id="title-and-subtitle-font-sizes">Title And Subtitle Font Sizes<a class="headerlink" href="#title-and-subtitle-font-sizes" title="Permanent link"></a></h4>
+<p>You can change the font sizes for titles and subtitles throughout the presentation.</p>
 <h5 id="page-title-size-pagetitlesize">Page Title Size - <code>pageTitleSize</code><a class="headerlink" href="#page-title-size-pagetitlesize" title="Permanent link"></a></h5>
 <p><a id="page-title-size-pagetitlesize"></a></p>
-<p>You can specify the point size of each slide that isn&rsquo;t a section divider or title slide. The size is specified in points.</p>
+<p>You can specify the point size of the first title line of each slide that isn&rsquo;t a section divider or title slide. The size is specified in points.</p>
 <p>Example:</p>
 <pre><code>pageTitleSize: 24
 </code></pre>
 <p>The default is 30 points.</p>
 <p>You can override this value on a slide-by-slide basis with <a href="#pagetitlesize-dynamic">Dynamic PageTitleSize</a>.</p>
+<p><strong>Notes:</strong></p>
+<ol>
+<li>The first title line is terminated by <code>&lt;br/&gt;</code>. There might be only one line in the title.</li>
+<li>When a title spills onto a second line that is not treated as a new title line.</li>
+<li>Lines after the first line can have a different font size. (See <a href="#page-subtitle-size-pagesubtitlesize"><code>pageSubtitleSize</code></a>.)</li>
+</ol>
+<h5 id="page-subtitle-size-pagesubtitlesize">Page Subtitle Size - <code>pageSubtitleSize</code><a class="headerlink" href="#page-subtitle-size-pagesubtitlesize" title="Permanent link"></a></h5>
+<p><a id="page-subtitle-size-pagesubtitlesize"></a></p>
+<p>You can specify the point size of the second and subsequent title lines of each slide that isn&rsquo;t a section divider or title slide. The size is specified in points.</p>
+<p>Example:</p>
+<pre><code>pageSubtitleSize: 22
+</code></pre>
+<p>The default is 30 points (the same as <a href="#page-title-size-pagetitlesize"><code>pageTitleSize</code></a>.)</p>
+<p>You can override this value on a slide-by-slide basis with <a href="#pagesubtitlesize-dynamic">Dynamic PageSubtitleSize</a>.</p>
+<p><strong>Notes:</strong></p>
+<ol>
+<li>The title lines are terminated by <code>&lt;br/&gt;</code>.</li>
+<li>When a title spills onto another line that is not treated as a new title line.</li>
+</ol>
 <h5 id="section-title-size-sectiontitlesize">Section Title Size - <code>sectionTitleSize</code><a class="headerlink" href="#section-title-size-sectiontitlesize" title="Permanent link"></a></h5>
 <p><a id="section-title-size-sectiontitlesize"></a></p>
 <p>You can specify the point size of the title text for each slide that&rsquo;s a section divider slide. The size is specified in points.</p>
@@ -3723,6 +3751,11 @@ <h4 id="pagetitlesize"><code>PageTitleSize</code><a class="headerlink" href="#pa
 <p>You can override the presentation <a href="#page-title-size-pagetitlesize">PageTitleSize</a> metadata value - perhaps to allow room for more text in the title of a slide:</p>
 <pre><code>&lt;!-- md2pptx: pagetitlesize: 16 --&gt;
 </code></pre>
+<p><a id="pagesubtitlesize-dynamic"></a></p>
+<h4 id="pagesubtitlesize"><code>PageSubtitleSize</code><a class="headerlink" href="#pagesubtitlesize" title="Permanent link"></a></h4>
+<p>You can override the presentation <a href="#page-subtitle-size-pagesubtitlesize">PageSubtitleSize</a> metadata value - perhaps to allow room for more text in the title of a slide:</p>
+<pre><code>&lt;!-- md2pptx: pagesubtitlesize: 14 --&gt;
+</code></pre>
 <p><a id="basetextsize-dynamic"></a></p>
 <h4 id="basetextsize"><code>BaseTextSize</code><a class="headerlink" href="#basetextsize" title="Permanent link"></a></h4>
 <p>You can override the presentation <a href="#specifying-text-size-with-basetextsize-and-basetextdecrement">BaseTextSize</a> metadata value. For example:</p>
diff --git a/user-guide.log b/user-guide.log
index 4190df7..ded7bfa 100644
--- a/user-guide.log
+++ b/user-guide.log
@@ -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 = 17&colon;43
-Def date = 18 February&comma; 2023
+Def time = 16&colon;50
+Def date = 25 February&comma; 2023
 Def TOC = Table Of Contents
 Def md = Markdown
 Def pp = Powerpoint
@@ -86,6 +86,7 @@ CSV Stop
 ..... .....  Metadata Keys
 ..... ..... .....  Title And Subtitle Font Sizes
 ..... ..... ..... .....  Page Title Size - `pageTitleSize`
+..... ..... ..... .....  Page Subtitle Size - `pageSubtitleSize`
 ..... ..... ..... .....  Section Title Size - `sectionTitleSize`
 ..... ..... ..... .....  Section Subtitle Size - `sectionSubtitleSize`
 ..... ..... ..... .....  Presentation Title Size - `presTitleSize`
@@ -185,6 +186,7 @@ CSV Stop
 ..... ..... ..... .....  `CodeForeground`
 ..... ..... ..... .....  `CodeBackground`
 ..... ..... .....  `PageTitleSize`
+..... ..... .....  `PageSubtitleSize`
 ..... ..... .....  `BaseTextSize`
 ..... ..... .....  `BaseTextDecrement`
 ..... ..... .....  `ContentSplitDirection`
diff --git a/user-guide.md b/user-guide.md
index ee40c69..0734269 100644
--- a/user-guide.md
+++ b/user-guide.md
@@ -73,6 +73,7 @@ In this document we'll refer to it as "md2pptx", pronounced "em dee to pee pee t
 	* [Metadata Keys](#metadata-keys)
 		* [Title And Subtitle Font Sizes](#title-and-subtitle-font-sizes)
 			* [Page Title Size - `pageTitleSize`](#page-title-size-pagetitlesize)
+			* [Page Subtitle Size - `pageSubtitleSize`](#page-subtitle-size-pagesubtitlesize)
 			* [Section Title Size - `sectionTitleSize`](#section-title-size-sectiontitlesize)
 			* [Section Subtitle Size - `sectionSubtitleSize`](#section-subtitle-size-sectionsubtitlesize)
 			* [Presentation Title Size - `presTitleSize`](#presentation-title-size-prestitlesize)
@@ -166,6 +167,7 @@ In this document we'll refer to it as "md2pptx", pronounced "em dee to pee pee t
 			* [`CodeForeground`](#codeforeground)
 			* [`CodeBackground`](#codebackground)
 		* [`PageTitleSize`](#pagetitlesize)
+		* [`PageSubtitleSize`](#pagesubtitlesize)
 		* [`BaseTextSize`](#basetextsize)
 		* [`BaseTextDecrement`](#basetextdecrement)
 		* [`ContentSplitDirection`](#contentsplitdirection)
@@ -209,7 +211,7 @@ The flat file format that md2pptx uses is Markdown. Using Markdown has further a
 * Markdown is compact; The files are tiny.
 * Markdown is used in popular sites, such as [Github](https://github.com).
 
-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.
+Every piece of text you use to create a Powerpoint presentation with md2pptx is valid Markdown - [with very few exceptions](#deviations-from-standard-markdown). 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.
 
@@ -309,6 +311,7 @@ To quote from the python-pptx license statement:
 
 |Level|Date|What|
 |:-|-:|:-|
+|3.5.1|25&nbsp;February&nbsp;2023|Added support for separately scaling second and subsequent slide title lines - with [`pageSubtitleSize`](#page-subtitle-size-pagesubtitlesize).|
 |3.5|18&nbsp;February&nbsp;2023|Added support for GraphViz .dot file rendering within triple backticks|
 |3.4.1|23&nbsp;October&nbsp;2022|Added support for a few more [slide transitions](#slide-transitions-transition): `wipe`&comma; `vortex`&comma; `fracture`&comma; `split`&comma; and `push`.|
 |3.4|16&nbsp;October&nbsp;2022|Added support for a small number of [slide transitions](#slide-transitions-transition).|
@@ -469,8 +472,6 @@ You can code multiple lines, as with [Presentation Title slides](#presentation-t
 
 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
 
@@ -480,15 +481,20 @@ The title of the slide is defined by coding a Markdown Heading Level 3.
 	* Bullet Two
 	* Bullet Three
 
+The title of the slide is defined by coding a Markdown Heading Level 3 (`###`).
+
+**Note:** You can allow the title to spill onto a second line but it is better to break titles up using `<br/>`. Doing so enables md2pptx to layout slide contents below the title better. It also allows you to specify a different (probably) smaller font size for the second and subsequent lines of the title.
+
+
 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](#task-list-slides).
+**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](#task-list-slides).
 
 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`](#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.
+**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`](#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
 <a id="numbered-items"></a>
@@ -1238,7 +1244,7 @@ md2pptx will throw away HTML comments, rather than adding them to the output fil
 
 The one exception is the use of [Dynamic Metadata](#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.
+**Note:** Other Markdown processors will copy the comment into the output file. Put nothing in the comments that is sensitive.
 
 ## Special Text Formatting
 <a id="special-text-formatting"></a>
@@ -1510,10 +1516,13 @@ As described in [Creating Slides](#creating-slides), md2pptx will populate the f
 The following sections describe each of the metadata keys.
 
 #### Title And Subtitle Font Sizes
+
+You can change the font sizes for titles and subtitles throughout the presentation.
+
 ##### Page Title Size - `pageTitleSize`
 <a id="page-title-size-pagetitlesize"></a>
 
-You can specify the point size of each slide that isn't a section divider or title slide. The size is specified in points.
+You can specify the point size of the first title line of each slide that isn't a section divider or title slide. The size is specified in points.
 
 Example:
 
@@ -1523,6 +1532,30 @@ The default is 30 points.
 
 You can override this value on a slide-by-slide basis with [Dynamic PageTitleSize](#pagetitlesize-dynamic).
 
+**Notes:**
+
+1. The first title line is terminated by `<br/>`. There might be only one line in the title.
+1. When a title spills onto a second line that is not treated as a new title line.
+1. Lines after the first line can have a different font size. (See [`pageSubtitleSize`](#page-subtitle-size-pagesubtitlesize).)
+
+##### Page Subtitle Size - `pageSubtitleSize`
+<a id="page-subtitle-size-pagesubtitlesize"></a>
+
+You can specify the point size of the second and subsequent title lines of each slide that isn't a section divider or title slide. The size is specified in points.
+
+Example:
+
+	pageSubtitleSize: 22
+
+The default is 30 points (the same as [`pageTitleSize`](#page-title-size-pagetitlesize).)
+
+You can override this value on a slide-by-slide basis with [Dynamic PageSubtitleSize](#pagesubtitlesize-dynamic).
+
+**Notes:**
+
+1. The title lines are terminated by `<br/>`.
+1. When a title spills onto another line that is not treated as a new title line.
+
 ##### Section Title Size - `sectionTitleSize`
 <a id="section-title-size-sectiontitlesize"></a>
 
@@ -2750,6 +2783,13 @@ You can override the presentation [PageTitleSize](#page-title-size-pagetitlesize
 
     <!-- md2pptx: pagetitlesize: 16 -->
 
+<a id="pagesubtitlesize-dynamic"></a>
+#### `PageSubtitleSize`
+
+You can override the presentation [PageSubtitleSize](#page-subtitle-size-pagesubtitlesize) metadata value - perhaps to allow room for more text in the title of a slide:
+
+    <!-- md2pptx: pagesubtitlesize: 14 -->
+
 <a id="basetextsize-dynamic"></a>
 #### `BaseTextSize`
 
diff --git a/user-guide.mdp b/user-guide.mdp
index 70a8de1..3a6d486 100644
--- a/user-guide.mdp
+++ b/user-guide.mdp
@@ -36,7 +36,7 @@ Builds of this very documentation are checked that way.
 * Markdown is compact; The files are tiny.
 * Markdown is used in popular sites, such as [Github](https://github.com).
 
-Every piece of text you use to create a &pp; presentation with md2pptx is valid &md; - with very few exceptions. \
+Every piece of text you use to create a &pp; presentation with md2pptx is valid &md; - [with very few exceptions](#deviations-from-standard-markdown). \
 While it might not render exactly the same way put through another &md; processor, it is generally equivalent. \
 This is one of the key aims of md2pptx.
 
@@ -152,6 +152,7 @@ To quote from the python-pptx license statement:
 =colalign l r l
 =csv
 Level,Date,What
+3.5.1,25&nbsp;February&nbsp;2023,Added support for separately scaling second and subsequent slide title lines - with [`pageSubtitleSize`](#page-subtitle-size-pagesubtitlesize).
 3.5,18&nbsp;February&nbsp;2023,Added support for GraphViz .dot file rendering within triple backticks
 3.4.1,23&nbsp;October&nbsp;2022,Added support for a few more [slide transitions](#slide-transitions-transition): `wipe`&comma; `vortex`&comma; `fracture`&comma; `split`&comma; and `push`.
 3.4,16&nbsp;October&nbsp;2022,Added support for a small number of [slide transitions](#slide-transitions-transition).
@@ -323,8 +324,6 @@ You can code multiple lines, as with [Presentation Title slides](#presentation-t
 Bullet slides use &md; bulleted lists, which can be nested. \
 This example shows two levels of nesting.
 
-The title of the slide is defined by coding a &md; Heading Level 3.
-
 
 	### This Is A Bullet Slide
 
@@ -334,9 +333,18 @@ The title of the slide is defined by coding a &md; Heading Level 3.
 	* Bullet Two
 	* Bullet Three
 
+The title of the slide is defined by coding a &md; Heading Level 3 (`###`).
+
+**Note:** \
+You can allow the title to spill onto a second line but it is better to break titles up using `<br/>`. \
+Doing so enables md2pptx to layout slide contents below the title better. \
+It also allows you to specify a different (probably) smaller font size for the second and subsequent lines of the title.
+
+
 Bulleted list items are introduced by an asterisk.
 
-**NOTE:** Some dialects of &md; allow other bullet markers but md2pptx doesn't. \
+**Note:** \
+Some dialects of &md; allow other bullet markers but md2pptx doesn't. \
 You can be sure by coding `*` you have valid &md; that md2pptx can also process correctly. \
 For an explanation of why you have to stick to `*` see [here](#task-list-slides).
 
@@ -345,7 +353,8 @@ md2pptx doesn't have a limit on the level of nesting but &pp; 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`](#specifying-how-many-spaces-represent-an-indentation-level-with-indentspaces). \
+**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`](#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
@@ -370,7 +379,8 @@ While the first will indeed be numbered "1" the second will be numbered "2", des
 
 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.
+**Note:** \
+You can mix numbered and bulleted items in a list.
 
 ### Graphics, Video And Audio slides
 <a id="graphics-video-and-audio-slides"></a>
@@ -589,7 +599,8 @@ For the types of graphics supported see [Graphics File References](#graphics-fil
 
 For how to make such graphics clickable or have a tooltip see [Clickable Pictures](#clickable-pictures).
 
-**Note:** Regular Markdown processors don't support pictures in tables; They render the `|` characters literally. \
+**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
@@ -613,7 +624,8 @@ For the types of graphics supported see [Graphics File References](#graphics-fil
 
 For how to make such graphics clickable or have a tooltip see [Clickable Pictures](#clickable-pictures).
 
-**Note:** Regular Markdown processors don't support pictures in tables; They render the `|` characters literally. \
+**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
@@ -658,7 +670,8 @@ For the types of graphics supported see [Graphics File References](#graphics-fil
 
 For how to make such graphics clickable or have a tooltip see [Clickable Pictures](#clickable-pictures).
 
-**Note:** Regular Markdown processors don't support pictures in tables; They render the `|` characters literally. \
+**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
@@ -681,7 +694,8 @@ For the types of graphics supported see [Graphics File References](#graphics-fil
 
 For how to make such graphics clickable or have a tooltip see [Clickable Pictures](#clickable-pictures).
 
-**Note:** Regular Markdown processors don't support pictures in tables; They render the `|` characters literally. \
+**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
@@ -759,7 +773,8 @@ For example you might code `&#x2776;` to place &#x2776; 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-metadata).
+**Note:** \
+You can more precisely control how code slides are laid out and their colours with [Code Metadata](#code-metadata).
 
 #### `<code>`
 
@@ -774,7 +789,8 @@ Surround the block of text by `<code>` and `</code`:
     }
     </code>
 
-**Note:** It, as in HTML, does not support `<span>` elements.
+**Note:** \
+It, as in HTML, does not support `<span>` elements.
 
 #### Triple Backticks (```)
 
@@ -789,7 +805,8 @@ Surround the block of text by them:
     }
     ```
 
-**Note:** It does not support `<span>` elements.
+**Note:** \
+It does not support `<span>` elements.
 
 <a id="special-processing-of-code-within-triple-backticks"></a>
 ##### Special Processing Of Code Within Triple Backticks
@@ -841,7 +858,8 @@ Each line of the code fragment - to be displayed in a monospace font - is indent
 	    for i in range(10):
 	        print(i)
 
-**Note:** It does not support `<span>` elements.
+**Note:** \
+It does not support `<span>` elements.
 
 #### `<pre>`
 
@@ -856,7 +874,8 @@ Surround the block of text by `<pre>` and `</pre`:
     }
     </pre>
 
-**Note:** It, as in HTML, **does** support `<span>` elements. \
+**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:
@@ -996,7 +1015,8 @@ For those cases you can start a slide in a two basic ways:
 
 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.
+**Note:** \
+If you continue a numbered list onto a new slide its number will reset to 1.
 
 ### Using A Horizontal Rule
 
@@ -1189,7 +1209,8 @@ md2pptx will throw away HTML comments, rather than adding them to the output fil
 The one exception is the use of [Dynamic Metadata](#dynamic-metadata). \
 md2pptx will honour these.
 
-**NOTE:** Other &md; processors will copy the comment into the output file. \
+**Note:** \
+Other &md; processors will copy the comment into the output file. \
 Put nothing in the comments that is sensitive.
 
 ## Special Text Formatting
@@ -1488,10 +1509,13 @@ The one type of item that won't be removed is any Action Buttons. See [Sample Ma
 The following sections describe each of the metadata keys.
 
 #### Title And Subtitle Font Sizes
+
+You can change the font sizes for titles and subtitles throughout the presentation.
+
 ##### Page Title Size - `pageTitleSize`
 <a id="page-title-size-pagetitlesize"></a>
 
-You can specify the point size of each slide that isn't a section divider or title slide. \
+You can specify the point size of the first title line of each slide that isn't a section divider or title slide. \
 The size is specified in points.
 
 Example:
@@ -1502,6 +1526,31 @@ The default is 30 points.
 
 You can override this value on a slide-by-slide basis with [Dynamic PageTitleSize](#pagetitlesize-dynamic).
 
+**Notes:**
+
+1. The first title line is terminated by `<br/>`. There might be only one line in the title.
+1. When a title spills onto a second line that is not treated as a new title line.
+1. Lines after the first line can have a different font size. (See [`pageSubtitleSize`](#page-subtitle-size-pagesubtitlesize).)
+
+##### Page Subtitle Size - `pageSubtitleSize`
+<a id="page-subtitle-size-pagesubtitlesize"></a>
+
+You can specify the point size of the second and subsequent title lines of each slide that isn't a section divider or title slide. \
+The size is specified in points.
+
+Example:
+
+	pageSubtitleSize: 22
+
+The default is 30 points (the same as [`pageTitleSize`](#page-title-size-pagetitlesize).)
+
+You can override this value on a slide-by-slide basis with [Dynamic PageSubtitleSize](#pagesubtitlesize-dynamic).
+
+**Notes:**
+
+1. The title lines are terminated by `<br/>`.
+1. When a title spills onto another line that is not treated as a new title line.
+
 ##### Section Title Size - `sectionTitleSize`
 <a id="section-title-size-sectiontitlesize"></a>
 
@@ -1744,7 +1793,8 @@ The values you can use for `BoldColour` and `ItalicColour` are:
 
 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`.
+**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>
@@ -1859,7 +1909,8 @@ To remove it specify:
 
 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`. \
+**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
@@ -1907,7 +1958,8 @@ The default is `addTableLines: no` which doesn't add any table lines.
 
 You can override this metadata item with [Dynamic Metadata](#addtablelines-dynamic).
 
-**Note:** This capability never removes lines - for example if they are present in the template presentation.
+**Note:** \
+This capability never removes lines - for example if they are present in the template presentation.
 
 <a id="adding-lines-after-table-rows-and-columns-with-addtablerowlines-and-addtablecolumnlines"></a>
 ##### Adding Lines After Table Rows And Columns With `addTableRowLines` And `addTableColumnLines`
@@ -1927,7 +1979,8 @@ specifies tables will have horizontal lines below the first row (often a header)
 
 You can override both these metadata items with [Dynamic Metadata](#addtablecolumnlines-and-addtablerowlines-dynamic).
 
-**Note:** This capability never removes lines - for example if they are present in the template presentation.
+**Note:** \
+This capability never removes lines - for example if they are present in the template presentation.
 
 <a id="specifying-what-the-added-table-lines-look-like-with-addtablelinecolour-addtablelinecount-and-addtablelinewidth"></a>
 ##### Specifying What The Added Table Lines Look Like With `addTableLineColour`, `addTableLineCount` and `addTableLineWidth`
@@ -2173,7 +2226,8 @@ You can specify a number of things about the bottom of each slide:
 * You can specify how much space to reserve at the bottom of the slide for things like slide numbers - with [`NumbersHeight`](#specifying-how-much-space-to-reserve-for-slide-numbers-with-numbersheight).
 * You can add "pseudo-footer" information in three places at the bottom of the slide. These are not genuine footer elements but are more flexible. See [Specifying Footer Text](#specifying-footer-text).
 
-**Note:** This user guide will use the term "footer" rather than "pseudo-footer".
+**Note:** \
+This user guide will use the term "footer" rather than "pseudo-footer".
 
 ##### Slide Numbers - `numbers`
 <a id="slide-numbers-numbers"></a>
@@ -2295,7 +2349,8 @@ To achieve this demotion you only need to specify the top level in the slide hie
 
 The other heading levels will be adjusted accordingly.
 
-**Note:** You obviously need to code the Title Slide at Heading Level 2, for example.
+**Note:** \
+You obviously need to code the Title Slide at Heading Level 2, for example.
 
 <a id="slides-with-multiple-content-blocks"></a>
 #### Slides With Multiple Content Blocks
@@ -2448,7 +2503,8 @@ If you create a "Plain Style" &TOC; slide, it will look something like this:
 <img src="https://raw.githubusercontent.com/MartinPacker/md2pptx/master/plainTOC.png" />
 </div>
 
-**Note:** With Plain Style, Section slides are unaffected; \
+**Note:** \
+With Plain Style, Section slides are unaffected; \
 They are rendered as if no &TOC; functions were used.
 
 ##### Table Of Contents Style - `tocStyle`
@@ -2482,7 +2538,8 @@ Enable live links by coding
 
 	tocLinks: yes
 
-**Note:** You cannot control the colour of links in Powerpoint. \
+**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-colour-tocitemcolour).
 
 
@@ -2517,7 +2574,8 @@ If you don't specify this the default Powerpoint background colour for shapes is
 
 This option was introduced because when [live links](#table-of-contents-live-links-toclinks) are used in &TOC; 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.
+**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`
 <a id="table-of-contents-row-gap-tocrowgap"></a>
@@ -2664,7 +2722,8 @@ Here are the values you can specify for the metadata:
 
 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). \
+**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` or`pop`, though these are destructive.
 
 #### Tables
@@ -2825,6 +2884,13 @@ You can override the presentation [PageTitleSize](#page-title-size-pagetitlesize
 
     <!-- md2pptx: pagetitlesize: 16 -->
 
+<a id="pagesubtitlesize-dynamic"></a>
+#### `PageSubtitleSize`
+
+You can override the presentation [PageSubtitleSize](#page-subtitle-size-pagesubtitlesize) metadata value - perhaps to allow room for more text in the title of a slide:
+
+    <!-- md2pptx: pagesubtitlesize: 14 -->
+
 <a id="basetextsize-dynamic"></a>
 #### `BaseTextSize`