Markdown format reference

Format version 1.1.0. This reference uses the same examples as Insert / formats in the editor and the same catalogue returned by the API and MCP.

Basics

Separate slides with --- on its own line, outside fenced code and comments.
Send Markdown as the md string in a JSON body. JSON encodes newlines as \n; decoded Markdown must contain real newline characters.
A single body newline creates a visible line break. An empty line starts a separate paragraph.
Use # for a cover heading, ## for a slide heading and ### for a smaller heading.
MCP workflow: get_format_reference, list_themes, write Markdown, validate_markdown, then create_presentation.

Text

Headings support levels H1–H6. Bold, italic, inline code, bullet lists, ordered lists and quotes are supported.
A shared heading such as # Project update | Apply all is used where the slide has no local heading of that level.

Heading

Main heading.

# Heading

Subheading

Slide heading.

## Subheading

Small heading

Third-level heading.

### Heading

Line breaks

A newline separates sentences within the same paragraph. An empty line starts another paragraph.

First sentence.
Second sentence.

Another paragraph.

Bold

Wraps the selected text.

**Text**

Italic

Wraps the selected text.

*Text*

Inline code

Wraps the selected text.

`code`

List

Bullet list.

- First item
- Second item

Numbered list

Ordered steps.

1. First step
2. Second step

Quote

Highlight a quote.

> An idea to remember.

Slides

Layouts: cover, title, section, v-split, grid, caption, title-image, default. Without a layout directive, MDSlides detects the layout from content.
hidden: true omits a slide from presenting, sharing and exports, while retaining it in the editor.
Speaker notes are private in public links and PDF; PowerPoint includes editable speaker notes.

New slide

Separates slides on its own line.

---

Cover

Applies the layout to the current slide.

<!-- layout: cover -->

Title and content

Applies the layout to the current slide.

<!-- layout: title -->

Section

Applies the layout to the current slide.

<!-- layout: section -->

Split layout

Applies the layout to the current slide.

<!-- layout: v-split -->

Grid layout

Applies the layout to the current slide.

<!-- layout: grid -->

Image with caption

Applies the layout to the current slide.

<!-- layout: caption -->

Title and image

Applies the layout to the current slide.

<!-- layout: title-image -->

Default layout

Applies the layout to the current slide.

<!-- layout: default -->

Appearance

Text that does not fit is shrunk automatically (down to 35%) in preview, presentation, PDF and PowerPoint;  keeps the theme size on that slide and  restores it.
Add | Apply all as the final parameter of footer, logo, align, title-align, valign, fit, layout, background or appearance directives to set a deck default, including future slides. Without it, the directive is local.
Local settings override shared defaults. Shared defaults survive reordering and deletion. If multiple shared defaults use the same key, the last wins.
The editor Apply all checkbox repeats other content blocks across existing slides; it does not create a global Markdown rule for arbitrary text or charts.
Legacy first-slide dark/light appearance is a deck default. Use global-appearance for an explicit default; the editor preserves it when inserting a local override.
Footer text is plain text, at most 300 characters. align: left/center/right; color: #RGB or #RRGGBB; size: 8–32 CSS pixels. The label does not restrict sharing.
Markdown logo positions: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right. Use a public image URL and a positive pixel size, for example 50px.
background selects a named background ID defined in the theme, not an arbitrary image URL.

Dark presentation

Changes the deck default; preserves individual slide overrides.

<!-- global-appearance: dark -->

Dark slide

Only affects the current slide.

<!-- dark -->

Light presentation

Changes the deck default; preserves individual slide overrides.

<!-- global-appearance: light -->

Light slide

Only affects the current slide.

<!-- light -->

Text aligned left

Aligns the text horizontally on the current slide.

<!-- align: left -->

Heading aligned left

Aligns headings only; keeps the body text alignment.

<!-- title-align: left -->

Text aligned center

Aligns the text horizontally on the current slide.

<!-- align: center -->

Heading aligned center

Aligns headings only; keeps the body text alignment.

<!-- title-align: center -->

Text aligned right

Aligns the text horizontally on the current slide.

<!-- align: right -->

Heading aligned right

Aligns headings only; keeps the body text alignment.

<!-- title-align: right -->

Content at the top

Positions the heading and body vertically on the current slide. Combine it with horizontal alignment.

<!-- valign: top -->

Content at the center

Positions the heading and body vertically on the current slide. Combine it with horizontal alignment.

<!-- valign: center -->

Content at the bottom

Positions the heading and body vertically on the current slide. Combine it with horizontal alignment.

<!-- valign: bottom -->

Footer at the left

Slide footer independent of body content. Edit the text, align (left/center/right), hex color and size (8–32 px). Visible in public links and exports; it does not prevent sharing.

<!-- footer: Confidential | align: left | color: #dc2626 | size: 12 -->

Footer at the center

Slide footer independent of body content. Edit the text, align (left/center/right), hex color and size (8–32 px). Visible in public links and exports; it does not prevent sharing.

<!-- footer: Confidential | align: center | color: #dc2626 | size: 12 -->

Footer at the right

Slide footer independent of body content. Edit the text, align (left/center/right), hex color and size (8–32 px). Visible in public links and exports; it does not prevent sharing.

<!-- footer: Confidential | align: right | color: #dc2626 | size: 12 -->

Logo

Current slide logo: change URL, position and size. Add | Apply all for the entire deck.

<!-- logo: url(https://example.com/logo.png) position(bottom-right) size(50px) -->

No automatic text fit

Text that does not fit shrinks automatically. This keeps the theme size on the current slide; add | Apply all for the entire deck.

<!-- fit: off -->

Theme background

Removes the slide-specific background and uses the background defined by the theme.

Remove the local background override to use the theme default.

Content

Image placeholders use an image fence with prompt: and optional ratio: (1:1, 16:9, 9:16, 3:2 or 2:3). Generate from the editor preview using your OpenAI key. Completed image fences retain prompt, ratio, image ID and an external HTTPS url:. Optional composition fields: position: left|right|center|full; width: 45% or 320px; height: auto, 50% or 240px; fit: contain|cover. Pixels use the 960 by 540 slide coordinate space. Full-slide covers behind text. Optional masks: shape: rectangle|rounded|circle|ellipse, radius: 24px (0–960px). Circle forces a square box; ellipse follows width and height. Full-slide is always rectangular. Files are hosted externally; library access is private but image URLs are public.
Use Markdown images and links with public URLs. External images depend on availability and export access.
Columns use <columns> with <col> children. Grids use <grid> with <cell> children; put the tags on separate lines.
Fenced code is displayed without execution. Arbitrary HTML is not a portable MDSlides extension; executable HTML is sanitized.

AI image

Prompt and aspect ratio; generate from the preview or reuse your image library.

```image
prompt: Un bosque al amanecer, estilo acuarela
ratio: 16:9
position: right
width: 45%
height: auto
fit: contain
```

Link

Uses the selected text as the label.

[Text](https://example.com)

Image

Replace the URL and describe the image.

![Description](https://example.com/image.png)

Table

Edit the headings and rows.

| Item | Value |
|---|---|
| A | 10 |
| B | 20 |

Two columns

Write Markdown inside each column.

<columns>
<col>
### Column 1

Text in the first column.
</col>
<col>
### Column 2

Text in the second column.
</col>
</columns>

Grid

Write Markdown inside each cell.

<grid>
<cell>
### First cell

Content.
</cell>
<cell>
### Second cell

Content.
</cell>
</grid>

Code block

Displays code without running it.

```js
const message = "Hello";
```

Charts

Use a fenced chart block. Types: bar, horizontal-bar, line, pie, donut, waterfall.
Options: type, unit (up to 20 characters), labels: true/false, points: true/false. points controls markers on line charts.
Tables require a category column and 1–7 numeric series for bar/line, exactly one numeric series for pie/donut, or category/value/role for waterfall.
Use 1–60 data rows, decimal dots and no thousands separators. Pie/donut values must be nonnegative with a positive total.
Waterfall roles are total or change; totals must match accumulated changes.

Bars

Example data: use decimal dots, no thousands separators. Options: unit: € and labels: false.

```chart
type: bar
labels: true

| Category | Value |
|---|---|
| A | 10 |
| B | 20 |
```

Lines

Example data: use decimal dots, no thousands separators. Options: unit: € and labels: false.

```chart
type: line
labels: true
points: true

| Month | Sales | Target |
|---|---|---|
| January | 10 | 12 |
| February | 20 | 18 |
```

Horizontal bars

Example data: use decimal dots, no thousands separators. Options: unit: € and labels: false.

```chart
type: horizontal-bar
labels: true

| Category | Value |
|---|---|
| A | 10 |
| B | 20 |
```

Pie

Example data: use decimal dots, no thousands separators. Options: unit: € and labels: false.

```chart
type: pie
labels: true

| Category | Value |
|---|---|
| A | 10 |
| B | 20 |
```

Donut

Example data: use decimal dots, no thousands separators. Options: unit: € and labels: false.

```chart
type: donut
labels: true

| Category | Value |
|---|---|
| A | 10 |
| B | 20 |
```

Waterfall

Example data: use decimal dots, no thousands separators. Options: unit: € and labels: false.

```chart
type: waterfall
labels: true

| Item | Value | Role |
|---|---|---|
| Initial | 100 | total |
| Change | 20 | change |
| Final | 120 | total |
```

Speaker notes

Private in public links and PDF; visible on screen when opened during presenting.

<!-- notes:
Write your notes here.
-->

Hide slide

Kept in the editor; omitted when presenting, exporting and sharing.

<!-- hidden: true -->

Themes

Use list_themes or GET /api/v1/themes to retrieve actual theme IDs. Omit theme_id to use builtin:default. Personal themes have UUIDs; display names are not IDs.
Themes are CSS snapshots copied into a presentation. A theme logo is deck-wide and overrides the Markdown logo.
Chart variables: --chart-color-1 through --chart-color-7, --chart-text, --chart-grid, --chart-positive, --chart-negative and --chart-total. Footer variables: --footer-size, --footer-color, --footer-bottom.
Sharing is opt-in: share defaults to false. Set share: true only when a public link is requested.

Shared formatting example

<!-- footer: Confidential | align: left | color: #dc2626 | size: 12 | Apply all -->
<!-- title-align: right | Apply all -->
## Results
First sentence.
Second sentence.

---
## Next steps
- Review
- Publish

Validation checks supported syntax and common errors. It does not guarantee visual fit, image availability, factual accuracy or safe arbitrary HTML.