Markdown Notes

Use --notes <path> to keep speaker notes in a separate Markdown file:

dais --notes talk_notes.md talk.pdf

The Markdown file becomes the notes source for the presentation. Dais still loads sidecars for slide grouping, timings, annotations, text boxes, and other metadata, but notes from the Markdown file replace sidecar notes for matching logical slides.

This is useful when notes are generated by another tool, edited by hand, or reviewed in Git.

Basic Format

Each top-level Markdown heading starts notes for one logical slide:

# Motivation

Opening notes.

# Prior Work

Mention the comparison.

# Main Result

Slow down here.

Without explicit slide numbers, Dais assigns sections in order. The first heading maps to slide 1, the second to slide 2, the third to slide 3, and so on. The heading text is only a label for the notes file; it does not need to match the slide title in the PDF.

Slide Numbers

Add {slide=N} to a top-level heading when a section belongs to a specific one-based logical slide:

# Motivation

Opening notes.

# Prior Work

Mention the comparison.

# Main Result {slide=4}

Slow down here.

This maps Motivation to slide 1, Prior Work to slide 2, leaves slide 3 without notes, and maps Main Result to slide 4.

After an explicit slide number, automatic numbering continues from the next slide:

# Backup Context {slide=12}

Notes for slide 12.

# Extra Detail

Notes for slide 13.

Use explicit slide numbers to skip slides or to keep generated notes stable when slides are inserted, hidden, or reordered.

Headings Inside Notes

Only top-level headings (# Heading) start a new slide note. Lower-level headings stay inside the current note:

# Main Result {slide=4}

## Setup

Explain assumptions.

## Punchline

State the result clearly.

Here, ## Setup and ## Punchline are part of the slide 4 notes.

Rules

  • Slide numbers are one-based logical slide numbers.
  • A top-level heading may contain any title text before {slide=N}.
  • Slides may be omitted.
  • Each slide can have at most one note section.
  • Note sections cannot refer to slide 0 or to slides past the end of the presentation.

Saving

When --notes <path> is active, note edits made in Dais save back to the Markdown file.

Dais preserves the structure of the file where possible:

  • Existing note headings keep their title text and {slide=N} marker.

  • Only note bodies are replaced.

  • Front matter, comments, blank lines, ordinary text outside note sections, and section order are preserved.

  • When notes are added for a slide with no existing section, Dais appends a new section:

    # Slide 7 {slide=7}

  • When notes are cleared, Dais leaves the heading in place with an empty body.

Sidecar saves continue to write non-note presentation metadata. With --notes <path>, the Markdown file remains the source of truth for notes.

Errors

Dais refuses to save the Markdown notes file when doing so could corrupt or mis-map notes. This includes:

  • A malformed {slide=N} marker.
  • Duplicate sections for the same slide.
  • A section mapped outside the presentation’s logical slide range.
  • A read or write error for the notes file.

When a save fails, Dais keeps the edited notes in the running presentation and reports the error so the file can be fixed.