Titles & Hierarchy
Every presentation has a hierarchy: in simplest terms, there's usually a Title slide which gives us the title of the document itself (the H1), followed by slides with their own titles (H2s), subtitles (H3s), and so on. This is called a Semantic Hierarchy – and allows Composer to understand more about the role each slide plays in the show.
Markdown indicates Titles with the Hash / Number / Pound-Sign character (the Octothorpe) + a space: the number of Hashes used indicates where we are in the structural hierarchy:
Title Hierarchies:
# Presentation or Divider Title
## Content Slide Title
### Content Slide Subtitle
Title hierarchies: use Hash characters to indicate where we are in the hierarchy of the presentation to steer the appropriate layout response.
Using an H1 – the single Hash – tells Composer to use a Title or Divider-type layout. An H2 indicates what we think of as common Interior layouts – the gamut of "Title &" layout types such as Title & Bullets, Title, Bullets & Photo, Title Only, and so on. And if you're targeting a theme that includes Subtitles on the Content slides(Chicago, Umbra, many of Apple's newer themes), you can use the H3 to specify it in context:
Title & Bullets with Subtitle:
## Slide Title
### Slide Subtitle Element
- A basic List: first item.
- The second item of the List.
- Another List item.
---
Title, Subtitle + Body builds: use an H3 to specify the Subtitle element in supporting Themes.
Stand-alone H3 Titles will eventually short-hand to "Caption &" routes when one of our themes are indicated as the build target – for now, they're interpreted the same as H2s (unless preceeded by an H2 on the slide), and you can route to the Caption-tier layouts via Named Routes.
Bullets & Lists
As noted above, a basic Bullet List is defined by using a single Dash character + a space:
Basic Bullets Slide:
- A basic List: first item.
- The second item of the List.
- Another List item.
---
Bullet Basics: use a simple Dash character + a space to add a bullet.
As there's no Title element present on this slide, it will route to the default Bullets slide.
You can also use a Numbered List instead of the unordered Dash style – however this will not result in a Numbered List being produced on the slide unless the Layout defaults to a Numbered List style: the Layout's defaults take precedence here, and can't (currently) be changed via the resulting Build Script.
From a hierarchal standpoint, Bullets are a "Core Route" indicator (much like a Title), and take precedence – regardless of order-of-appearance – over any remaining paragraphs on the slide when evaluating the appropriate layout response. So the following variation on the Title & Bullets from above:
Title & Bullets with Paragraph:
## Slide Title
A brief introductory paragraph:
- A basic List: first item.
- The second item of the List.
- Another List item.
---
Would result in the same output as the previous Title, Subtitle & Bullets example: the List takes precedence over the paragraph, which Composer will then map to an available Subtitle element if one is available on-slide (even if it comes after the List in the Markdown).
Nested Lists are supported: simply Tab-indent the sub-items under their parent item in your Markdown editor:
Title & Bullets with Nested List Items:
## Slide Title
- A basic List: first item.
- Sub-Item 1 of the First Item
- Sub-Item 2 of the First Item
- The second item of the main List.
- Another List item.
---
Nested Lists: toggle into a Nested List by indenting the sub-items in your editor.
Note that Nested Lists require Keystroke Support at run-time: you'll need to add or toggle the Script Editor item in the System Settings > Privacy & Security > Accessibility screen in MacOS to enable before your Build Script is run.
Paragraphs & Styling
Paragraphs are the root / default element in a Markdown file: type a paragraph, and add an empty line to indicate we're moving on to the next:
Basic Paragraphs:
Paragraph 1 Lorem Ipsum Aenean lacinia bibendum nulla sed consectetur. Lorem ipsum dolor sit amet, consectetur adipiscing elit mollis semper.
Paragraph 2 Lorem Ipsum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec ullamcorper nulla non metus auctor fringilla.
Markdown uses the Asterisk character to denote basic Styling information, such as Italics, Bold, or Bold Italic settings:
Basic Styling:
*Italic Characters* are surrounded by a single Asterisk.
**Bold Characters** are surrounded by two Asterisks.
***Bold Italic Characters*** are surrounded by three Asterisks.
**Bold and *Italic* can be mixed** in cumulative order.
Indicate Styling: use Asterisk characters to indicate Bold or Italic formatting.
There are other patterns you might use to distinguish between those depending on the flavor of Markdown you prefer – Composer should understand any of the common variants allowed in the CommonMark standard, but fall back to Asterisks if you encounter runtime issues.
Pulling both of those together, we can define a basic Title slide with relevant Style information like so:
Title Slide with Styling:
# The Presentation Title
The Presentation Subtitle with a **big, bold idea** emphasized for impact.
---
Markdown supports a few additional style & formatting definitions that we currently ignore: Strikethrough is ignored completely on the parse (as editorial residue). Likewise, Subscript and Superscript are currently unhandled (Keynote won't allow the character-level text selection needed to perform the key command via AppleScript, and unicode character substitution produces mediocre results), though will be included as unformatted text on the slide for further editing post-build.
Photos & Media
We can add a Photograph to the slide to add additional impact: Markdown uses two different variations for Photos, depending on whether the file is Local (on Your Computer) or Remote (at a Web URL):
Local vs Remote Images:
![[Wiki-link Style Local Image.png]]
At present, all Local images need to reside in a shared, common Assets folder: if Local Images are indicated, the Build Script that Composer outputs will prompt you for that folder before it builds the show.
Remote Images include the complete URL to the image, which must be web accessible without additional interaction (such as a sign-in or click event).
Re-visiting our prior Title Slide, then, to add a Photo simply involves adding a new line with the image file name wrapped in the appropriate tag style:
Title Slide with Styling + Local Photo:
# The Presentation Title
The Presentation Subtitle with a **big, bold idea** emphasized for impact.
![[MyCoverImage.png]]
---
Photo Titles: here, we've added a Local-style image to the Title slide.
Or likewise with our prior Title & Bullets to make a simple Title, Bullets & Photo layout:
Title, Bullets & Photo (Remote Photo):
## Slide Title
- A basic List: first item.
- The second item of the List.
- Another List item.
---
Common Variants: here, we've added a Remote image to the previous Title & Bullets slide.
Initial Multi-Photo support is in place: at this time, the standard Photo - 3 Up layout is the only active target when using Generic theme routing – you'll otherwise need to specify a Target Layout that includes the correct amount of placeholders. You can target the standard Photo or Photo - 3 Up layouts by including only image elements on the slides:
Photo-only layout, Photo - 3 Up layout:
---
---
If you're still in Draft mode but want to indicate a photo placeholder should be included in the Layout, you can include a Tagged variant of the Local-style image (we'll dig deeper into Tags below):
Title Slide w/ Photo Placeholder:
# The Presentation Title
The Presentation Subtitle with a **big, bold idea** emphasized for impact.
![[::placeholder-image::]]
---
Indicate Placeholders: here, we're using the "::placeholder-image::" tag in a Local Image wrapper: this will include an image on the layout manifest without specifying a target image.
Additional Media Types such as Video or Audio are not supported at this time (but will follow similar nomenclature once implemented).
Quote Slides
Markdown supports Quotation Elements by starting the line with a Greater Than character + a space ahead of the text, like so:
Basic Quote Slide:
> Quote element lorem ipsum dolor, sit amet. Nullam quis risus eget urna mollis ornare vel eu leo.
Attribution Name
---
Basic Quotes: use a Greater Than character + a space to indicate a Quotation.
Because of the way Quote layouts are defined in Keynote, the Quote will map to the Body element, and the remaining paragraph will map to the placeholder beneath (presumed to be the Attribution element, if we're unable to target by placeholder contents). Titles are contra-indicated, though you can add a Photo if you're targeting a theme that includes a Photo Quote layout (such as Chicago or Disruptor X).
We've handled Quote Slides differently over the years (as has Apple): in some cases, you'll want to include Quote characters at the begining or end of the quoted text, or avoid using them altogether on themes that include a graphical glyph on the layout.
Tables & Charts
Tables are supported, though take a bit of getting used to formatting-side: if you're using an app like Obsidian for authoring, there are a few plugins available that make it a bit easier to visualize the rows & columns, but if you're drafting on-the-fly it's straightforward if you follow a few simple principles.
To create a Table in Markdown, wrap the Columns in Pipe characters, with a Row of Three Dash Rules separating the Header Row from the Body, followed by wrapped cells. For example, a 3-Column, 2-Row Table:
Basic Table:
| Header 1 | Header 2 | Header 3 |
| --- | --- | --- |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
---
Basic Tables: wrap the columns in Pipe characters, with a row of 3-dash Rules separating the Header Row from the Body.
Tables in Keynote almost always default to center alignment within the cells – you can affect the Column alignments by adding Colon characters around the 3-Dash Rules to "weight" the alignment. Here, the Left Column (Header 1) is set to Left alignment, the Center Column (Header 2) is explicity set to Center, and the right-most Column (Header 3) is set to Right-alignment:
Basic Table Alignments (Left/Center/Right):
| Header 1 | Header 2 | Header 3 |
| :--- | :---: | ---: |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
---
Table Alignment: add Colon characters around the 3-Dash rules to indicate Alignment for the column.
We break from standard Markdown here to add an additional condition: Row Headers. To indicate that you'd like to turn on Row Headers on your table, leave the first Header Column empty, and wrap the Row Headers in Bold:
Basic Table with Row Headers:
| | Header 1 | Header 2 | Header 3 |
| --- | --- | --- | --- |
| **Row Header 1** | Cell 1 | Cell 2 | Cell 3 |
| **Row Header 2** | Cell 4 | Cell 5 | Cell 6 |
---
Row Headers: leave the first Header Column Blank and Bold the first Column Cells to trigger Row Header styling.
If you only need Row Headers – i.e. no visible Column Headers at all – you can leave the Header Row blank: empty Piped fields still need to be present to define the column structure before the 3-Dash Rules, but they won't appear on-slide.
Basic Table with Row Headers Only:
| | | | |
| --- | --- | --- | --- |
| **Row Header 1** | Cell 1 | Cell 2 | Cell 3 |
| **Row Header 2** | Cell 4 | Cell 5 | Cell 6 |
---
Row Headers Only: leave the Column Header Pipes empty to completely suppress the Header Row formatting.
And following the same principles, if you don't want Column or Row Headers present, you'll need empty Column headers to establish the structure, and the plain cells from the first example:
Basic Table, no Column or Row Headers:
| | | |
| --- | --- | --- |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
---
Cells Only: leave the Header Columns empty to suppress Header Row styling.
Tables otherwise default to the first (default) Table style defined within the target theme, so you'll need to do some post-build tweaking if you need to apply an alternate style to the table itself or affect specific cell formatting beyond basic Bold/Italics.
We don't have Chart support in place yet: we'll end up in a similar space to Table nomenclature (since Charts are Tables underneath), but need to work up the additional indicators/triggers we'll standardize around. More to come.
Fenced Code
While Markdown has a specific formatting for demarking Fenced Code Blocks, Composer does not support the tag at this time: we'll essentially need to re-invent Prism as an AppleScript function to handle it well, which will take a bit of planning. On the Back-burner, but more to come.
For the time being, we recommend a Title-Only slide and setting the Code block manually once the Build has finished.
Presenter Notes
You can add Presenter Notes to any slide by starting a new line with the Caret character + a space ahead of the text:
Title & Bullets with Presenter Notes:
## Slide Title
- A basic List: first item.
- The second item of the List.
- Another List item.
^ A Presenter Note to add to this slide.
---
