Read and adjust your slides

Whether your assistant wrote the slides or you did, they are a plain text file in Markdown: a way to add simple formatting to plain text. A few marks alongside the words tell mdeck what is a heading, a list, or a new slide.

You do not have to write Markdown yourself. But knowing these marks lets you read what the assistant wrote, check it, and fix a word or a number without asking. Markdown is also what AI assistants write most naturally, which is why mdeck uses it.

Headings and paragraphs#

Put # and a space before the main heading. Use ## and a space for a smaller heading. Leave a blank line between paragraphs.

# Our next adventure

This is a paragraph of ordinary text.

## Where we are going

This paragraph explains a little more.

Keep each slide focused on one idea. If your words do not fit, make another slide rather than making all the text smaller.

Start another slide#

Write three dashes on a line of their own:

# The first idea

Some words about it.

---

# The next idea

Some more words.

Lists, emphasis, and links#

Put each list item on its own line:

- Bring a notebook.
- Ask **one good question**.
- Share what you learn.

Give a slide some settings#

You can tell mdeck which layout to use. Put this small settings block at the beginning of a slide:

:::meta
layout: focus
:::
# One idea worth remembering.

The opening :::meta and closing ::: mark the settings. The line between them asks for the focus layout: a large statement slide. The words beneath the block are the slide's content.

You do not need a settings block on every slide. The layout guide gives you complete examples to copy.

Give a slide a lasting link#

Add an id when you want to link directly to a particular slide:

:::meta
id: questions
:::
# Your questions

You can then add #questions to the presentation's address. IDs must be unique within the talk and start with a letter. Use letters, numbers, hyphens, or underscores, with no spaces.

Settings for the whole presentation#

A settings block at the very top of the file controls the whole presentation. It uses --- around its contents:

---
theme: neue
palette: swiss
meta:
  title: "Our next adventure"
  author: "Alex Morgan"
---

---
:::meta
layout: title
:::
# Our next adventure
## A plan we can share

Keep the spaces before title and author: they put those values inside the meta group. Use spaces rather than tabs. Quoting text is helpful when it contains punctuation.

For a talk in German, add lang: de to these settings. The page is then marked as German, which helps screen readers and hyphenation, and the words mdeck adds for your audience, such as the buttons for readers and polls, are German too.

Put several files together#

A course, or a talk built from parts you also give on their own, can be one deck made of others. A slide with nothing but an :::include line stands for all the slides of another file:

---
theme: neue
meta:
  title: "Algorithms, autumn term"
---

---
# Welcome

---
:::include ./lectures/01-sorting.md

---
:::include ./lectures/02-graphs.md slides=3-7

Each included file stays a deck of its own: mdeck run lectures/02-graphs.md still presents it alone, with its own theme and settings. Included, its slides come along with what they need: its references, its components, its own callout names, its hotspots setting and its time, which its slides share as they do when it is shown alone. The look (theme, palette, size, language) is that of the deck that includes it. A file of slides without settings of its own can be included too. slides=3-7 (or slides=2, slides=1,4-6) keeps some of them, numbered as that file shows them.

Pictures, videos and drawings in an included file are found from its own folder, wherever it lies. A deck in another language takes the included file in that language where there is one: course.de.md including ./lectures/02-graphs.md shows 02-graphs.de.md beside it. An included file may include others.

Edit the slides of an included file in that file. The editor shows the include as one card naming the file, and while mdeck run is open, a change to that file appears in the deck straight away. Times saved after a rehearsal go into the file each slide is written in. mdeck check checks every file, and names the file and line of a problem.

Reading older examples#

Older decks put slide settings between --- lines too:

---
layout: focus
---
# One idea worth remembering.

This still works. For new slides, the explicit :::meta form makes it easier to see where settings end and writing begins.