Markdown syntax
ippon uses a hand-written parser for a subset of Markdown. Think of it as regular Markdown with a few additions for slides.
Frontmatter
You can put a simple frontmatter block of key: value lines at the top of the file.
---title: 発表タイトルauthor: あなたの名前description: 説明(任意)lang: jaurl: https://slides.example.com/talk/---title… the HTML<title>andog:title.author/description… go into<meta>tags (descriptionalso goes intoog:description).lang…<html lang>(defaultja).url… where you publish the slides. It becomesog:url, and the absolute URL of the cover image made withippon ogp(<input>.png) goes intoog:image.image… replaces theog:imageimage (a path relative tourl, or an absolute URL).
Syntax rules
ippon adds only three kinds of syntax of its own. New syntax will follow the same rules.
| Kind | How to write it | Role | Example |
|---|---|---|---|
| Slide directive | ::...:: on the first line of a slide |
Sets how the whole slide looks | ::center bg=blue size=2:: |
| Block line | ::name ...:: on a line of its own |
Places something at that spot, or splits the slide | ::right:: ::note:: ::qr:: ::http:: ::background:: |
| Line prefix | A marker at the start of a paragraph or code line | Changes how that paragraph or line is treated | -# note, !! in code |
Each line prefix applies to a different scope.
-#works per paragraph. Put it at the start of the first line of a paragraph and the whole paragraph (including the following lines up to a blank line) becomes a small note. If you put it on a line in the middle of a paragraph, it is shown as is, so write the note as a separate paragraph after a blank line.!!works per code line. Inside a code block, it highlights only the line it is on.
Directive and block line contents
- The contents are keywords (
center,caption) andkey=valuepairs (bg=blue,url=https://...), separated by spaces. - Values cannot contain spaces (write
%20for a space in a path or URL). - You can omit the key for the main value.
::qr https://...::,::http https://...::, and::background img/a.jpg::are the same as writingurl=/url=/path=respectively. - Keys that take a number (
size=,brightness=,opacity=) must be written as numbers. - Unknown
key=valuepairs in a block line are ignored on their own (::background a.jpg foo=1::is a background ofa.jpg).
When you make a mistake
ippon shows syntax it cannot read as plain text. Slides don’t disappear and the build doesn’t stop.
- If the
::...::on the first line contains even one unknown keyword, it is no longer a directive. If it can then be read as a block line, it becomes one (::qr https://...::or::background img/a.jpg::on the first line becomes a QR code or a background); otherwise it becomes a plain paragraph. - A block line missing a required value, such as
urlfor::qr::,urlfor::http::, orpathfor::background::, also becomes a plain paragraph. - Values that are clearly malformed (
brightness=red, a QR code URL that is too long) fail the build so you notice.
Color backgrounds and image backgrounds
Backgrounds are written differently depending on their role.
- A color sets how the whole slide looks, so write it with
bg=in the first-line directive (::bg=blue::,::center bg=#222::). - An image has a placement (the whole slide or the right half), so write it with the
::background::block line.
If you write both, the image is layered on top of the color. Lower the image’s opacity= to let the color show through.
Compatibility
From v1 on, these rules and the existing syntax stay compatible. Removing or changing syntax requires a major version bump.
Slide breaks
A line containing only --- separates slides. --- inside a code fence does not.
# 1 枚目
---
# 2 枚目Directives
Put ::...:: on the first line of a slide to set how that slide looks.
You can combine them, as in ::center bg=blue size=2::.
| Directive | Meaning |
|---|---|
::center:: |
Large centered text (for one-message slides) |
::title:: |
Cover slide. The last paragraph is pushed to the bottom of the page |
::wide:: |
Narrower left and right margins (for screenshots) |
::bg=blue:: |
Background color. blue / orange / purple / red / green / black / white, or #rrggbb |
::size=1.5:: |
Text size multiplier |
With bg=white, the slide automatically switches to a light theme (dark text).
Two columns (::right::)
The right column starts at the ::right:: line. A leading heading is placed outside (above) the columns.
## 見出し
- 左に説明- もうひとつ
::right::
```tsconst app = new Hono()```Change the column widths with ::right left-wide:: (1.4 : 1) or ::right right-wide:: (1 : 1.4).
Columns are top-aligned by default. If one side holds something tall, such as a photo, the other side looks crammed at the top.
Write ::right center:: to center the columns vertically on that slide only.
You can combine it with a width, as in ::right right-wide center:: (in any order).
Body text
- Headings:
#/##/### - Lists:
-*, numbered1.. Indent to nest. - Bold
**bold**is shown in the accent color. `inline code`, italic, links[text](url), images.- Blockquotes
>, tables (|-separated; put---under the header row and use:--and similar to set alignment; write|inside a cell as\|). - Arrows
→are shown slightly dimmed. -# note… a small note.
Code blocks
```tsconst x = 1!! const y = 2 // start a line with "!! " to highlight it```Supported highlighting: hcl / tf / terraform, sh / bash / shell / zsh, json,
js / javascript / ts / typescript / jsx / tsx, yaml / yml, py / python, go / golang, rust / rs,
html / xml / svg, css, diff / patch, console.
console colors lines starting with $ as commands and lines containing Error or panic, or starting with make: ***, as errors.
diff colors whole lines: lines starting with + as additions (green) and lines starting with - as deletions (red).
It also colors @@ hunk headers and --- / +++ file headers. You can combine it with !! .
```diff@@ -1,2 +1,2 @@-const port = 3000!! +const port = Number(process.env.PORT ?? 3000)```Highlighting works one line at a time, so comments and strings that span multiple lines are not colored after the first line.
In the built HTML, a Copy button appears at the top right of each code block.
Speaker notes (::note::)
Everything after ::note:: becomes the speaker note for that slide. It is not shown on the slide itself,
only in the presenter view and the phone remote.
本番に出る内容
::note::
ここは手元のメモ。QR codes (::qr::)
Write ::qr url=https://...:: to embed a QR code for that URL in the slide as SVG.
It is generated at build time, so it needs no network and shows up in PDFs as is.
::qr url=https://github.com/under18dev/ippon-slides::::qr https://example.com caption::- You can omit
url=and write just the URL. - Add
captionto show the URL in small text under the QR code (hidden by default). - The QR code always has a white background so it stays readable on any background color (
bg=). - You can also put it inside a
::right::column. - URLs can be up to 213 bytes. Longer URLs fail the build.
Background images (::background::)
Write a ::background path=img/photo.jpg:: line to use that image as the slide background.
The image fills the screen and the overflow is cropped (object-fit: cover). Text sits on top of the image.
::center::
::background path=img/stage.jpg brightness=0.4::
# 文字を乗せる| Parameter | Meaning |
|---|---|
path= |
Image path (relative to the Markdown file, or a URL). You can omit path= and write just the path |
brightness= |
Brightness. 1 is unchanged, 0.5 is half as bright. Around 0.3 to 0.5 keeps text on top readable |
opacity= |
Opacity. 1 is unchanged, 0 is invisible. The slide’s background color (bg=) shows through |
Write it after ::right:: to cover only the right half of the screen (from the right column to the right edge, full height).
This gives a layout with text on the left and a photo on the right. It follows left-wide / right-wide widths too.
## 自己紹介
- 名前- やっていること
::right::
::background path=img/me.jpg::- Relative image paths are rewritten for the output location just like
<img>, and embedded with--inline. - Background images do not zoom when clicked.
HTTP playground (::http::)
Use ::http method=GET url=https://...:: to show an HTTP response on a slide.
See HTTP playground for details.