markdowndeveloper toolsAPIautomation

Markdown to Slides: A Practical Guide

February 15, 202612 min read

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 editorMarkdown API
Where/markdown, or Markdown to Slides on the create pagePOST /api/markdown
WhoAnyone can preview; sign in to save and to use AI featuresActive Business plan, with an API key from Settings
What you getLive slide preview, presentation mode, and optional AI generate, enhance and translate (uses AI credits)Parsed slide JSON, or a standalone Reveal.js HTML file
ExportsPDF, PowerPoint and HTML on paid plansJSON 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"
---
KeyEffect
titleDeck 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.
themeTheme 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 charactersTitle-style slide
Starts with >Quote
Is mostly - or * list items (at least two)Bullets
Contains an image and four lines or fewerMedia
Contains a fenced code blockCode
Anything elseContent

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

MarkdownNotes
**bold**, *italic*, ~~strike~~, `code`Inline formatting
- item, * item or 1. itemBulleted and numbered lists; indent an item to nest it
> quoteQuote block
![alt text](https://...)Image, returned as an image block in the JSON. Use absolute HTTPS URLs and descriptive alt text (accessible presentations)
[link](https://...)Link
GFM tablesHeader 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.
KeyEffect
notesSpeaker notes. Returned as "notes": [{"content": "..."}] in the JSON and placed in the HTML file's speaker view (press S while presenting)
layoutOverrides the detected layout. Use one of title-slide, content, bullets, quote, code, media or blank (blank drops the slide title from the HTML)
backgroundBackground 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 title and theme at 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:

#TitleLayoutSpeaker notes
1Platform Team Weekly Updatetitle-slideNone
2Shipped this weekbulletsYes
3Incidentscontent (table and a sentence)None
4Rollback commandcodeNone
5Decision neededquote (set with layout:)Yes
6Next weekbulletsNone

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:

Slide titled "Shipped this week" with three bullet points: faster build cache for the main repository, new on-call handbook published, two flaky integration tests removed

Slide titled "Rollback command" with one sentence and a dark code block containing a deploy script rollback command

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) and format (json, the default, or html).
  • 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

  1. One idea per slide. Separators are cheap; crowded slides are not.
  2. Always start a slide with a heading. It gives the slide a real title in every output.
  3. Keep bullets short. Three to five per slide, each a single line.
  4. Keep tables small. If a table needs more than five or six rows, split it or summarize it.
  5. Use absolute image URLs with descriptive alt text.
  6. 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.

Related Articles

Related Templates