REVELation Authoring Guide

This guide explains how to write REVELation presentations based on the current loader and presentation builder behavior.

Table of Contents

1. Core Concept

2. Slide Anatomy

3. Notes (Bottom Section)

4. Slide Markdown (Middle Section)

   • Full Markdown Reference
   • Language Variants Reference

5. Top Matter (Top Section)

6. Other

   • Heading-Based Slide Breaks

1. Core Concept

A presentation is a single Markdown file.

Slides are separated with marker lines:

Example:

# Slide 1

***

# Slide 2 (new horizontal stack)

---

# Slide 2.1 (vertical child slide)

---

2. Slide Anatomy

Each slide can have up to three optional sections:

1. Top Matter
2. Slide Markdown
3. Notes

All three are optional.

Practical convention:

• Top Matter is usually placed at the top of a slide.
• Slide Markdown follows it.
• Notes come after a :note: separator.

Important behavior notes:

• There is no hard parser boundary between "top matter" and "slide content" in raw markdown. This is mostly a writing convention.
• Builder UI recognizes top matter by known macro/background patterns near the start of the slide.
• Top matter items like sticky macros/backgrounds can persist across subsequent slides until changed or reset by another top matter section.

Template shape:

[optional top matter lines]

[optional slide markdown body]

:note:

[optional speaker notes]

3. Notes (Bottom Section)

Use a delimiter line before speaker notes:

:note:

Example:

# Main slide content

:note:

Say this quietly to the presenter audience only.

Notes are not rendered as regular slide content. They appear in notes/speaker views.

4. Slide Markdown (Middle Section)

4.1 Quick Markdown Primer

Markdown is a plain-text format used widely for docs, READMEs, wikis, and presentations.

Markdown Headings and Lists

# Heading 1
## Heading 2
### Heading 3

Regular paragraph text.

- Bullet item
- Another item

1. Numbered item
2. Next item

Markdown Formatting and Links

*Italic*
**Bold**
__Underline__
~~Strikethrough~~

[Link text](https://example.com)

See the Full Markdown Reference

4.2 Per-Slide Authoring Extensions

REVELation extends normal markdown with slide-focused syntax.

For multi-language presentation workflows, see Language Variants Reference.

Styled Headings and References

Wrap headings and references in underscore characters (Italics in standard markdown). These are converted to block-level headings, or right-justified references if they're at the end of the paragraph.

_Verse 1_

Fragments

Append ++ at the end of a line to reveal it incrementally:

- First point ++
- Second point ++

Attributions

Per-slide attribution:

:ATTRIB:Photo by Jane Smith

Magic images

Use special alt-text in Markdown-stle image tags to trigger special behavior

Syntax:

![keyword[:modifier]](source)

Common forms:

![background](sunrise.jpg)
![background:noloop](loop.mp4)
![background:sticky](stage.mp4)
![fit](chart.png)
![caption:Quarterly trend](chart.png)
![youtube](https://youtu.be/VIDEO_ID)
![youtube:fit](https://youtu.be/VIDEO_ID)
![web](https://example.com)
![web:scrollY=500](https://example.com)

Note: ![background:sticky]() is interpreted as a macro, so it will repeat on all slides and will also reset macros.

Media aliases

Define media once in front matter, reference with media:<alias>:

media:
  opener:
    filename: intro.mp4

![background](media:opener)

Inter-presentation links

Use standard markdown links:

[Next presentation](next.md)
[Jump in this deck](#section-anchor)

Path base rule:

• Markdown path targets are resolved from the presentation root directory (the folder containing index.html), not relative to the current markdown file path.
• This applies even when opening nested markdown files (for example ?p=nest1/nest2/deep.md).
• Parent-directory traversal targets such as ../other.md are blocked for safety.

Background audio

Use audio commands with either a local file or a media:<alias> source:

:audio:play:intro.mp3:
:audio:playloop:bed.mp3:
:audio:play:media:intro:
:audio:playloop:media:bed:
:audio:stop:

4.3 :commands: Reference

Line-based commands/macros commonly used while authoring:

5. Top Matter (Top Section)

Top matter is where you usually place sticky macros and sticky backgrounds intended to shape this slide and following slides.

5.1 Macros and stickiness

Macro calls use {{...}} and can be persisted slide-to-slide.

Common examples:

{{darkbg}}
{{lighttext}}
{{upperthird}}
{{bgtint:rgba(0,0,0,0.35)}}
{{transition:fade}}
{{animate}}
{{autoslide:15000}}

Sticky metadata helpers:

{{attrib:Photo by Jane Smith}}
{{ai}}

Reset persisted top-matter macro state:

{{}}

5.2 Sticky backgrounds

Use a sticky background image/video when you want it to carry forward:

![background:sticky](stage-loop.mp4)

Behavior detail:

• Sticky background participates in top-matter persistence.
• Applying a sticky background resets previous persisted macros, then establishes the new sticky baseline.

5.3 No hard boundary rule

Top matter is a convention, not a strict language block.

In practice:

• Keep top matter grouped at the top of each slide for readability.
• Put main content below it.
• Use :note: to begin notes.

This keeps files predictable in both the markdown source and builder UI.

6. Footnote: Heading-Based Slide Breaks

REVELation can also infer slide breaks from headings when the setting is enabled.

If newSlideOnHeading is omitted in YAML front matter, heading-based splitting may apply automatically (for compatibility workflows).

Recommended practice:

• Prefer explicit *** and --- separators.
• Use heading-based implied breaks only when needed for interoperability with other Markdown tooling.

Documentation Hub

Back to Documentation Hub