Markdown Authoring Guide

SlideCraft splits the Markdown you provide into "one-slide-at-a-time" blocks, interprets each block as a structure of title, body, figures, and so on, and then flows it into your template's colors, fonts, and layouts. This page gives a comprehensive overview of the Markdown notation for building slides.

Placement and styling are delegated to the template and the engine, so you can produce polished slides without shrinking font sizes by hand or micro-specifying coordinates. Only the notation for figures (diagrams) is extensive, so it lives in its own page: Diagrams.

Prerequisite

If you haven't installed the app yet, start with Installation. SlideCraft's philosophy (write → see → export) is also touched on at the top of each page.

---

Slide separator ---

A line that is nothing but --- (a horizontal rule) marks the boundary of a single slide. One slide is generated for each separator.

# 最初のスライド

- ポイント1
- ポイント2

---

# 次のスライド

本文テキスト。

The example above produces two slides. The separator is a line whose beginning is --- and nothing else. A GFM table's delimiter row (|---|---|) carries the leading pipe of a cell, so it is never confused with a slide separator.

TIP

A leading blank line is fine. The parser skips over any leading blank line that a separator leaves behind.

---

Title, subtitle, and body

Within a single slide, the role of each line is determined by its heading level and line type.

Notation	Role
# 見出し	The slide's title
## 見出し or > 引用	Subtitle
- / * bullets, paragraphs	Body
1. / 1) numbered lists	Body (auto-numbered; saved back as a 1. 2. … sequence)
### 見出し	A subheading inside a group (column/card/step)
**太字** / *斜体*	Inline styling

# 2026年 事業計画
> 第2四半期レビュー

- 売上は前年比 **+12%**
- 新規顧客は *120 社*

A few behaviors are worth keeping in mind.

• Only the first # becomes the title. Any # lines beyond the first are treated as body.
• The subtitle can be specified with either ## or > (a blockquote). However, > only becomes a subtitle when placed immediately after the title and before the body begins. A > that appears after the body has begun becomes an ordinary body line with the quote marker stripped.
• Only one subtitle is picked up, too.

A common mix-up

If you put a > line in the middle of the body, it is displayed as "body with the > stripped," not as a blockquote. Note that SlideCraft's Markdown is not a general-purpose Markdown viewer but a converter into slide structure.

---

Meta information Category: / Date: / Footer:

On title slides, lines beginning with Category: / Date: / Footer: are treated as meta information and flowed into the template's corresponding frames (category, date, footer).

# 2026年 事業計画
> 第2四半期レビュー

Category: 経営会議
Date: 2026-07-07
Footer: 社外秘

Points to remember:

• There are only three keys: Category / Date / Footer (case-insensitive). If any one of the three is present, that slide is treated as a title-type slide (a layout with meta frames is more likely to be chosen).
• Other keys such as Meta: or Summary: are not treated as meta and become body lines. Only the three above are treated specially.
• When you want to use a specific layout rather than leaving it to automatic selection, write <!-- slide: レイアウト名 --> on the first line of the block. Normally you can omit this and leave it to automatic selection (auto).

<!-- slide: title-centered -->
# 表紙タイトル

---

Conclusion band Takeaway: / source line Source:

Content slides can carry two field rows (a one-line Key: value) besides the body. When the template has a dedicated box for one, a layout with that box is chosen automatically and the row is flowed into it.

• Takeaway: — the slide's conclusion in one line. To keep "one slide, one message", write one on every content slide; the body then only supports it. Goes into the callout box (e.g. Midnight's Content.1Body.Single+1Callout).
• Source: — where the data comes from. Always write one on slides that show numbers, tables or charts. Goes into the source box (e.g. Midnight's Content.1Body.Single+1Source, or Table.1Table.Single+1Source for a table; the 出典 box of the 公文書 template).

# 地域別人口

| 地域 | 人口 |
|---|---|
| 東京 | 1400万 |

Takeaway: 人口は首都圏へ一極集中が続く
Source: 総務省 2025

Points to remember:

• The keys are Takeaway / Source (case-insensitive; Kicker below works the same way). They may appear anywhere in the slide (on export they are gathered after the slide body).
• Repeating a key adds one paragraph per line to its box (e.g. two sources).
• Unlike Category: and the other meta keys, a field row does not turn the slide into a title-type slide.
• They also work on slides with region separators (<!-- col --> / <!-- card --> …): the row belongs to the whole slide, not to the last region.
• A Source: line inside a code fence stays code.
• If the template (or the pinned layout) has no box for the row, the row is not exported. MCP get_deck_issues warns that the layout has no box for the Takeaway: row (showing it in the app's diagnostics panel is tracked in #419). Move it into the body, or use a template that has the box.

Category line Kicker:

Kicker: is the small category line above a content slide's title (e.g. SECTION 02 · Cost analysis). It is a field row like Takeaway: / Source:: if the template has a box whose name starts with Kicker / Eyebrow, a layout with that box is picked automatically and the row goes into it.

# コスト構造の内訳

- 人件費が 6 割
- 外注費が増加

Kicker: SECTION 02 · コスト分析

Things to know:

• Midnight Executive (the default template) has a content layout with a Kicker box, Content.1Body.Single+1Kicker: writing a Kicker: row picks that layout automatically and draws the row above the title. The other bundled templates (技術報告 / ビジュアルデッキ / 配布資料) do not have the box yet — there the row is not exported, as above, and get_deck_issues warns that the layout has no box for the Kicker: row. The AI guide (get_authoring_guide) mentions Kicker: only for templates that have the box.
• The category line of a title slide is still Category:. Writing Kicker: does not turn a slide into a title slide, and Category: keeps its meaning.
• To show which chapter a slide belongs to, use a chapter cover's <!-- section --> (below): on templates with a footer box, each slide from a chapter cover onward gets its chapter's name in the footer automatically. Use Kicker: for a label other than the chapter name.

---

GFM tables

A standard GFM (GitHub Flavored Markdown) table becomes a native PPTX table (cells editable in PowerPoint), not an image. It enters the body area as a table with a header row.

# 比較表

| 項目 | 旧プラン | 新プラン |
|------|---------|---------|
| 料金 | ¥1,000  | ¥800    |
| 容量 | 10 GB   | 30 GB   |

• A table is recognized as the pair of a | … | row and the delimiter row that immediately follows it (|---|---|).
• Wherever it appears in the body, only the first table becomes a native table.
• Because the table is not rasterized, you can edit its cells directly in the resulting PPTX.

---

Images ![alt](data:image...)

Writing ![alt](src) alone on a line makes it an embedded image.

Data URIs only

Only a data URI (data:image/...;base64,...) becomes an embedded image. For safety, a src that is a remote URL, a local path, javascript:, and the like is not turned into an image, and that line is treated as plain body text. Convert to a data URI before pasting it in.

# ロゴ

![会社ロゴ](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...)

Images are automatically included in the preview and the HTML output, and in the PPTX they are decoded and embedded as media. On a single slide, only the first image is picked up as an image; any image line beyond that falls back to body text.

Position, size, and crop attributes {...}

Appending {...} to the end of an image line lets you finely specify position, size, crop, and layer. Attributes are comma-separated key=value pairs.

![背景](data:image/png;base64,...){x=0,y=0,w=13.33,h=7.5,fit=cover,behind=1}

Key	Meaning	Value
x y	Top-left position (inches)	Number
w h	Width / height (inches)	Number
fit	How to fit into the frame	cover (crop to fill) / contain (fit the whole)
ar	The source image's aspect ratio (w/h)	Positive number
behind	Lay it on the backmost layer	1

Points to remember:

• The coordinate system is in inches on a 13.33 × 7.5 inch slide (x=0,y=0 is top-left; w=13.33,h=7.5 covers the full slide).
• x y w h take effect as a position specification only when all four are present. If you write only some of them, they are ignored and the image fills its allotted frame.
• An ![alt](src) with attributes omitted takes the default size that fills its allotted body frame.
• You can drag to move and resize in the visual editor, and the result is saved back into the Markdown as these {...} attributes (a round trip). Rather than writing by hand, it's easier to place first and then export.
• behind=1 lays the image on the backmost layer. This suits placing body text over a background photo or watermark pattern.
• The alt text in ![alt] is drawn as a one-line caption directly under the image (a description or source note), and becomes the picture's alt text in the PPTX. To omit the caption, leave the alt empty: ![](...). A backmost (behind=1) image gets alt text only, no caption.

Background images work on column-split slides too

Even on a slide split with <!-- col --> and the like, a standalone image line (especially a behind=1 background) is not taken into each column's body but is treated as the background of the whole slide.

---

Multi-column / KPI / Steps / Cards / Comparison

When you want to split a slide's body into multiple regions, use separator comments. Place separator comments of the same kind after # タイトル and write the content of each region between them.

Separator comment	Purpose
<!-- col -->	Multiple side-by-side columns
<!-- kpi -->	KPI (big-number) tiles
<!-- step -->	Process / procedure steps
<!-- card -->	Cards
<!-- compare -->	Two options side by side (Option A vs Option B)
<!-- before --> / <!-- after -->	A change from Before to After (As-is → To-be), with an arrow and Before/After labels

# 3本柱

<!-- col -->
### 品質
- 不良率を半減

<!-- col -->
### 速度
- リードタイム短縮

<!-- col -->
### コスト
- 原価 10% 削減

Usage notes:

• A separator comment must be on a line of its own (do not write body before or after it, as in <!-- col -->).
• Content written before the first separator comment does not go into any region, apart from the title/subtitle. The title (#) and subtitle (>) become the heading for the whole slide, and each region's content is written between the separators.
• In each region, ### 小見出し becomes the region's header, and bullets or paragraphs go beneath it.
• Aside from col (a plain column), kpi / step / card / compare / before·after act as hints to choose the corresponding layout (KPI tiles, process, cards, comparison). col is a plain side-by-side layout with no hint.

Comparing two options <!-- compare -->

Use <!-- compare --> to put two equal options side by side, such as Option A and Option B. The template's comparison layout (e.g. Compare.2Option.Versus, or 12_課題と対策 in the report templates) is chosen automatically; each region's ### heading names the option and the content goes below it.

# Option A or Option B

<!-- compare -->
### A: build in-house
- Lower upfront cost
- Six months to launch

<!-- compare -->
### B: outsource
- Higher upfront cost
- Live in one month

• The comparison layout holds two regions. With three or more, the slide is laid out as ordinary columns (<!-- col --> or a table suits a comparison of three or more).
• If the template has no comparison layout, the slide is also shown as ordinary columns.

Before and after <!-- before --> / <!-- after -->

To show a change from the left (current state) to the right (target state), such as an improvement proposal or a migration, use one <!-- before --> and one <!-- after -->. The slide uses the same layout as a comparison, plus an arrow between the two sides and a Before / After label above each side.

# Revising the approval flow

<!-- before -->
### Today
- Paper forms passed around
- 5 days to approval on average

<!-- after -->
### After the change
- Electronic approval in a workflow tool
- 1 day to approval on average

• The meaning comes from position: the first region is Before, the second is After. If you write them in the other order, the left side is still drawn as Before (and on export the markers are written back as before then after, matching what is drawn).
• The arrow and the labels use the template's theme accent color. If the template's layout already draws its own arrow (as 12_課題と対策 in the report templates does), that arrow is used and no second arrow is drawn.
• Regions after the second are also treated as After. This is a two-sided structure, so keep it to two regions.

Adding an icon to a heading

In a card / step / KPI region, start the ### heading with :icon-name: to place a built-in icon (the same set as diagram nodes) to the left of the heading. The :server: token itself is not printed.

<!-- card -->
### :server: Availability
- Redundant setup

• Icon names: router switch server database cloud firewall client internet load_balancer wireless_ap storage printer phone vpn monitor (aliases such as db→database and any letter case are accepted).
• An unknown name (e.g. :nosuch:) does not become an icon and stays as text (a typo never makes content disappear).
• It only becomes an icon at the start of the heading and without formatting (**:server:** stays as bold text).
• It is drawn when the slide lands on a group layout (cards, process, …); on other layouts it stays as text.

Highlighting the current step

To show "where we are" in a process band, write that step's separator as <!-- step * -->. Its heading becomes bold and its column gets a thin frame.

<!-- step -->
### Requirements

<!-- step * -->
### Design

<!-- step -->
### Build

• Only step accepts the * (not card / kpi).

Placing a figure in a region

Each region can hold a figure instead of body text. Writing a ```diagram or ```mermaid fence inside a region turns that region into a figure, which sits side by side with the other columns.

# 構成と指標

<!-- col -->
### 構成
```diagram
type: pie
nodes:
  - { id: a, label: 国内, value: 60 }
  - { id: b, label: 海外, value: 40 }
```

<!-- col -->
### 指標
- 稼働率 98%
- 月次成長 +12%

For the figure notation itself, see Diagrams.

---

Speaker notes <!-- note -->

Put <!-- note --> on its own line, and everything from there to the end of the slide (the next ---) becomes that slide's speaker notes. The note body is plain Markdown (multiple lines, bullets, **bold** allowed) and is never shown on the slide face.

# Proposal outline

- Only the takeaway on the slide

<!-- note -->
Speaker notes start here. Background you narrate aloud, data sources,
anticipated Q&A — multiple lines are fine.

- Bullets work too

Things to remember:

• Place the marker at the very end of the slide — everything after it is consumed as notes.
• Only the marker is invisible; the note body is ordinary Markdown paragraphs, so the source stays naturally readable on GitHub and other Markdown viewers.
• PPTX export produces PowerPoint's native speaker notes (the notes pane).
• In HTML export the notes are hidden by default; press n to toggle the notes panel (Editing & Export).
• When automatic overflow splitting occurs, the notes stay on the first slide only (they are not duplicated).
• A payload form like <!-- note: memo --> does not become notes (it stays a discarded comment, as before). Write the note body on the lines after the marker.

This suits the briefing style of "sparse slides, rich notes": move narration that would overflow the body budget into the notes instead.

---

Sections and table of contents <!-- section --> / <!-- toc -->

Chapter covers are not generated — they are ordinary slides you write. Put <!-- section --> on its own line inside the block of the slide you want to act as a chapter cover, and that slide is declared a chapter boundary. The chapter name stays a # heading, so the chapter structure remains readable in plain Markdown.

A slide block containing only <!-- toc --> becomes the table-of-contents slide. Its content (chapter numbers + names) is always re-derived from the section-tagged slides.

<!-- toc -->

---

<!-- section -->
# Current State

> optional chapter subtitle

---

# Detail slides of the chapter…

Things to remember:

• Chapter numbers are assigned automatically in order of appearance of section-tagged slides.
• The TOC cannot be edited by hand (only the single <!-- toc --> line is written back to Markdown). Rename a chapter cover's title and the TOC follows automatically on the next render/export — drift between the TOC and the actual chapters is structurally impossible.
• Orthogonal to the <!-- slide: LayoutName --> pin: a chapter cover can be auto-resolved (it tends to resolve to Section-family layouts) or pinned.
• Markdown without these tags exports exactly as before.

---

Code fences

A fenced block enclosed in ``` is handled differently depending on the fence's language name.

Fence	Handling
```diagram	Draw a native figure from a DiagramSpec (YAML/JSON) → Diagrams
```mermaid	Mermaid notation. Convertible ones become native figures; the rest fall back to a Mermaid image
Others (```yaml / ```python / a bare ``` with no language, etc.)	Displayed as monospace code / log

# 設定例

```yaml
server:
  port: 8080
  workers: 4
```

Fences not used for figures (yaml / python / bash / log, no language specified, and so on) are placed on the slide as-is as a monospace code block. The language name is preserved as a display hint.

Mermaid that can't be converted to a figure

Mermaid's gitGraph / sankey / C4 and the like cannot be converted to native figures and cannot be output to PPTX either. By default they are rejected at export time, and they never disappear silently. Replace them with a supported figure (the 12 types in Diagrams, or convertible Mermaid). For details, see the FAQ.

---

When the body overflows

When the body doesn't fit on a slide, the engine splits the overflow deterministically and distributes the content across multiple slides. It will not force-shrink the font to cram everything onto one slide. Long bullet lists can be made more readable by summarizing the content or organizing it into a GFM table. The built-in AI can help with summarizing, too (AI Setup).

---

Related pages

• Diagrams — 12 native types drawable with diagram / mermaid fences, plus 4 more via Mermaid
• Templates — the source of the look (color scheme, fonts, layouts)
• AI Setup — the built-in offline AI for generation and editing
• MCP — integration from an upstream AI agent
• FAQ — fixes for images becoming body, figures not appearing, and more