Markdown to Slides: A Practical Guide
Markdown to Slides: A Practical Guide
Markdown suits presentations that live alongside code or documentation. The text diffs cleanly in Git, reviewers can comment on a pull request, and a script can produce the file from data. SlidesMate reads Markdown in two places: the Markdown editor in the app, and a Markdown API for Business accounts.
This guide documents what the SlidesMate converter actually reads, shows a complete example file and what it becomes, and ends with a CI recipe. It is a supporting workflow: most SlidesMate decks start from a prompt, outline or document on the create page. For the endpoint contract itself, the API documentation is the authoritative reference.
Where Markdown Works in SlidesMate
| Markdown editor | Markdown API | |
|---|---|---|
| Where | /markdown, or Markdown to Slides on the create page | POST /api/markdown |
| Who | Anyone can preview; sign in to save and to use AI features | Active Business plan, with an API key from Settings |
| What you get | Live slide preview, presentation mode, and optional AI generate, enhance and translate (uses AI credits) | Parsed slide JSON, or a standalone Reveal.js HTML file |
| Exports | PDF, PowerPoint and HTML on paid plans | JSON or HTML only; no PDF or PowerPoint |
The API converts the Markdown you send. It does not write or rewrite content with AI.
The Syntax the Converter Reads
Slides and titles
- Put a line containing only three or more hyphens (
---) between slides. A---line inside a fenced code block is left alone, so you can show front matter or YAML in a code slide. - If the first line of a slide is a
#or##heading, it becomes the slide title. Otherwise the slide is titled "Slide 1", "Slide 2" and so on. - Everything after the title line is the slide body.
Front matter at the top of the file
An optional block between --- lines at the very start of the file sets deck-level values:
---
title: "Platform Team Weekly Update"
theme: "slate-corporate"
---
| Key | Effect |
|---|---|
title | Deck title, returned in the API response and used for the HTML file name. Defaults to "Untitled Presentation"; it is not taken from the first heading. |
theme | Theme ID for HTML output. If the ID is not recognized, the first theme (monochrome-news) is used. |
Each line is read as a simple key: value pair; nested YAML is not supported. Other keys such as author or date are accepted without error but do not currently change the output.
Theme IDs: monochrome-news, neon-noir, midnight-aurora, pastel-glass, rose-blush, split-pastel, mosaic-grid, organic-spine, forest-deep, saas-angular, startup-pitch, slate-corporate, serif-corporate, editorial-warm, paper-minimal, bold-frame, ocean-depth, white, black and serif. In the Markdown editor you can also pick a theme from the toolbar.
How layouts are chosen
The converter picks a layout for each slide from its body. The rules are applied in this order:
| If the slide body... | Layout |
|---|---|
| Has two non-empty lines or fewer and under 200 characters | Title-style slide |
Starts with > | Quote |
Is mostly - or * list items (at least two) | Bullets |
| Contains an image and four lines or fewer | Media |
| Contains a fenced code block | Code |
| Anything else | Content |
Because the first rule wins, a slide with a heading and only one or two short lines is treated as a title-style slide. To choose the layout yourself, add a layout: line at the top of the slide (see below).
Content inside a slide
| Markdown | Notes |
|---|---|
**bold**, *italic*, ~~strike~~, `code` | Inline formatting |
- item, * item or 1. item | Bulleted and numbered lists; indent an item to nest it |
> quote | Quote block |
 | Image, returned as an image block in the JSON. Use absolute HTTPS URLs and descriptive alt text (accessible presentations) |
[link](https://...) | Link |
| GFM tables | Header row, separator row, then body rows |
Fenced code block with a language tag (for example python) | Returned as a code block with its language in the JSON; syntax-highlighted in HTML output |
$...$ | Inline math, rendered with KaTeX. A dollar sign followed by a space or digit, as in "$8 a month", stays plain text |
$$ ... $$ | Display math, returned as a math block in the JSON and rendered with KaTeX |
Raw HTML tags in the Markdown are shown as literal text in the HTML output rather than executed, and links or images with javascript: URLs are removed.
Speaker notes and other per-slide settings
Lines in key: value form placed directly after a slide's --- separator, before its heading, are read as settings for that slide and are not shown on it:
---
notes: Pause for questions; the budget slide comes next.
layout: quote
## Decision needed
> Approve the budget before 15 November.
| Key | Effect |
|---|---|
notes | Speaker notes. Returned as "notes": [{"content": "..."}] in the JSON and placed in the HTML file's speaker view (press S while presenting) |
layout | Overrides the detected layout. Use one of title-slide, content, bullets, quote, code, media or blank (blank drops the slide title from the HTML) |
background | Background color for that slide in the HTML output, for example #0f172a |
For notes that run over several lines, indent the lines that follow notes:. Starting with notes: | keeps each line break; without the |, the lines are joined into one paragraph.
Only these lowercase keys are read, so an ordinary line such as "Note: figures are fictional" in the slide body stays on the slide. If you prefer to fence the settings, ---, the settings lines, then --- works the same way.
What the converter does not read
- Charts. Use a table, or an image of a chart you generated elsewhere.
- Nested YAML or front matter keys other than
titleandthemeat the top of the file.
A Complete Example
This file describes a fictional platform team's weekly update. It uses a bulleted list, a table, a code block, a quote, two speaker notes and one layout override:
---
title: "Platform Team Weekly Update"
theme: "slate-corporate"
---
# Platform Team Weekly Update
Week ending 30 October 2026 (fictional example)
---
notes: Thank the build team; the cache change came out of their hack week.
## Shipped this week
- Faster build cache for the main repository
- New on-call handbook published
- Two flaky integration tests removed
---
## Incidents
| Date | Service | Duration |
|------|---------|----------|
| 27 Oct | Search API | 18 min |
| 29 Oct | Billing webhooks | 6 min |
Both incidents are closed, and each has a written review.
---
## Rollback command
If the billing webhook fix misbehaves, on-call can revert it with:
```bash
./scripts/deploy.sh billing-webhooks --rollback v2.14.3
```
---
layout: quote
notes: Ask for a yes or no today; the migration window closes on 15 November.
## Decision needed
> Approve moving the staging database to the new region before 15 November.
---
## Next week
- Finish the region migration plan
- Review alert thresholds with the support team
- Retire the old status page
The file is also available to download as fixture.md. We sent it to a local build of SlidesMate's /api/markdown endpoint with a Business-plan API key on a test account on 3 November 2026 and saved the results unedited: the JSON response (pretty-printed) and the standalone HTML file. It produced six slides:
| # | Title | Layout | Speaker notes |
|---|---|---|---|
| 1 | Platform Team Weekly Update | title-slide | None |
| 2 | Shipped this week | bullets | Yes |
| 3 | Incidents | content (table and a sentence) | None |
| 4 | Rollback command | code | None |
| 5 | Decision needed | quote (set with layout:) | Yes |
| 6 | Next week | bullets | None |
Without its layout: quote line, slide 5 would be a title-style slide, because its body is a single short line.
These screenshots show slides 2 and 4 of the HTML file open in a browser:


Paste the file into the Markdown editor to check how it splits into slides and how each one is titled before automating anything.
Using the Markdown API
The API documentation covers authentication, request format, responses and errors. In brief:
- Endpoint:
POST https://slidesmate.com/api/markdown - Authentication:
Authorization: Bearer <key>. Create the key in Settings on an active Business plan. The full key is shown once; keep it on your server and out of browser code and repositories. - Body: JSON with
markdown(required, up to 100,000 characters) andformat(json, the default, orhtml). - Limits: 60 requests per minute per key.
- Errors: 400 for an invalid body, 401 for a missing or unknown key, 403 if the account is not on an active Business plan, 429 when rate-limited, 500 if conversion fails.
Send a local file with jq, which reads the whole file as one JSON string:
jq -Rs '{markdown: ., format: "json"}' weekly-update.md | \
curl -sS -X POST https://slidesmate.com/api/markdown \
-H "Authorization: Bearer $SLIDESMATE_API_KEY" \
-H "Content-Type: application/json" \
-d @- \
-o weekly-update.json
For the example file, the response starts like this (an excerpt of the saved response.json; id values are random on every request):
{
"success": true,
"data": {
"title": "Platform Team Weekly Update",
"theme": "slate-corporate",
"slideCount": 6,
"slides": [
{
"id": "MsJyFAfygjPFCnMBNSXc5",
"title": "Platform Team Weekly Update",
"content": "Week ending 30 October 2026 (fictional example)",
"contentType": "markdown",
"layout": "title-slide",
"contentBlocks": [ ... ]
},
{
"id": "_QTYDjsCJ6YQ_QuNs5Dc7",
"title": "Shipped this week",
"content": "- Faster build cache for the main repository\n- New on-call handbook published\n- Two flaky integration tests removed",
"contentType": "markdown",
"layout": "bullets",
"contentBlocks": [ ... ],
"notes": [
{ "content": "Thank the build team; the cache change came out of their hack week." }
]
}
]
}
}
Each slide object includes the parsed content blocks (text, code with language, images and math), which is what you need if you render slides in your own application. The theme field repeats the front matter value as written; only the HTML output checks it against the theme list.
JSON or HTML?
Use JSON when a pipeline needs to validate or transform the result, or when you render slides in your own application. Use HTML ("format": "html") when you want a single file someone can open in a browser; the response is downloaded as an attachment named after the deck title. The HTML file renders lists, tables, quotes, images, highlighted code and KaTeX math, and keeps speaker notes in the presenter view. It loads Reveal.js, KaTeX and the highlighting styles from a public CDN, so it needs an internet connection, and images must be reachable from the viewer's browser.
Neither format is a PowerPoint or PDF. If the final deliverable must be one of those, open the Markdown in the Markdown editor and export there on a paid plan.
CI Recipe: Convert Markdown on Every Push
This GitHub Actions workflow converts each Markdown file in docs/presentations/, fails the build if any conversion fails, and uploads the results as an artifact. Store the key as a repository secret named SLIDESMATE_API_KEY.
name: Convert slides
on:
push:
paths:
- 'docs/presentations/*.md'
jobs:
convert:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Convert Markdown to slide JSON
env:
SLIDESMATE_API_KEY: ${{ secrets.SLIDESMATE_API_KEY }}
run: |
set -euo pipefail
mkdir -p output
for file in docs/presentations/*.md; do
name=$(basename "$file" .md)
status=$(jq -Rs '{markdown: ., format: "json"}' "$file" | \
curl -sS -o "output/${name}.json" -w '%{http_code}' \
-X POST https://slidesmate.com/api/markdown \
-H "Authorization: Bearer $SLIDESMATE_API_KEY" \
-H "Content-Type: application/json" \
-d @-)
if [ "$status" != "200" ]; then
echo "::error::${file} returned HTTP ${status}"
cat "output/${name}.json"
exit 1
fi
jq -e '.success == true and .data.slideCount > 0' "output/${name}.json" > /dev/null
echo "${file}: $(jq -r '.data.slideCount' "output/${name}.json") slides"
jq -r '.data.slides[].title' "output/${name}.json"
sleep 1 # stay well under 60 requests per minute
done
- uses: actions/upload-artifact@v4
with:
name: slides
path: output/
Printing the slide titles in the log is a cheap review step: a slide titled "Slide 4" usually means a heading is missing. To produce browser-ready files as well, repeat the request with "format": "html" and save to output/${name}.html.
The same loop works in GitLab CI; place it under script: and limit the job with rules: - changes: [docs/presentations/*.md].
For a recurring report built from data, with validation before the API call, see how to automate presentation creation.
Tips for Better Markdown Slides
- One idea per slide. Separators are cheap; crowded slides are not.
- Always start a slide with a heading. It gives the slide a real title in every output.
- Keep bullets short. Three to five per slide, each a single line.
- Keep tables small. If a table needs more than five or six rows, split it or summarize it.
- Use absolute image URLs with descriptive alt text.
- Preview before you automate. The Markdown editor shows how each slide is parsed.
When Markdown Is the Wrong Tool
If the deck needs bespoke visual design, charts, custom layouts or real-time co-editing, build it in the visual editor instead: start from the create page or a template. Real-time collaboration is available on the Business plan.
If you have an existing Word or PDF report rather than slide-ready Markdown, start with document to presentation. The worked Word example includes the source, extracted text and exported draft.