コンテンツにスキップ

Markdown 記法

ippon は手書きの Markdown サブセットパーサーです。普通の Markdown に、スライド向けの 記法を少し足したものと考えてください。

frontmatter

ファイル先頭に key: value だけの簡単な frontmatter を書けます。

---
title: 発表タイトル
author: あなたの名前
description: 説明(任意)
lang: ja
url: https://slides.example.com/talk/
---
  • title … HTML の <title> と og:title。
  • author / description … <meta> に入る(description は og:description にも)。
  • lang … <html lang>(既定 ja)。
  • url … スライドを公開する場所。og:url になり、ippon ogp で作った表紙の画像(<input>.png)の絶対 URL を og:image に入れる。
  • image … og:image の画像を差し替える(url からの相対パス、または絶対 URL)。

記法の決まり

ippon 独自の記法は、次の 3 種類だけです。新しい記法もこの決まりに沿って足します。

種類 書き方 役割 例
スライドの指示 スライドの 1 行目の ::...:: そのスライド全体の見せ方を決める ::center bg=blue size=2::
ブロック行 独立した 1 行の ::名前 ...:: その場所に何かを置く、または区切る ::right:: ::note:: ::qr:: ::http:: ::background::
行頭の印 段落やコードの行の頭に付ける記号 その段落・行の扱いを変える -# 注釈、コードの !!

行頭の印は、効く範囲がそれぞれ違います。

  • -# は 段落単位。段落の 1 行目の頭に付けると、その段落全体(空行までの続く行も含む)が注釈になる。 段落の途中の行に付けても印のまま表示されるので、注釈は空行で区切った別の段落にする。
  • !! は コードの行単位。コードブロックの中で、付けた行だけを強調する。

指示とブロック行の中身

  • 中身は空白で区切った キーワード(center、caption)と キー=値(bg=blue、url=https://...)。
  • 値に空白は入れられません(パスや URL に空白があるときは %20 にする)。
  • 主役の値はキーを省略できます。::qr https://...::、::http https://...::、::background img/a.jpg:: は、 それぞれ url= / url= / path= を付けたのと同じです。
  • 数値を取るキー(size=、brightness=、opacity=)は数値で書きます。
  • ブロック行に知らない キー=値 が混ざっていても、そこだけ無視します(::background a.jpg foo=1:: は a.jpg の背景)。

書き間違えたとき

ippon は、読めなかった記法を 普通の文字として表示 します。スライドが消えたりビルドが止まったりはしません。

  • 1 行目の ::...:: に知らないキーワードが 1 つでも混ざっていたら、指示ではなくなる。 そのあとブロック行として読めればブロック行になり(1 行目の ::qr https://...:: や ::background img/a.jpg:: は QR や背景になる)、読めなければただの段落になる。
  • ::qr:: の url、::http:: の url、::background:: の path のように必須の値が無いブロック行も、ただの段落になる。
  • ただし、値の形が明らかにおかしいもの(brightness=red、長すぎる QR の URL)はビルドをエラーにして知らせる。

色の背景と画像の背景

背景は役割で書き方を分けています。

  • 色はスライド全体の見せ方なので、1 行目の指示 bg= で書く(::bg=blue::、::center bg=#222::)。
  • 画像は置く場所(全体か右半分か)があるので、ブロック行 ::background:: で書く。

両方を書くと、色の上に画像が重なります。opacity= で画像を薄くすると下の色が透けます。

互換性

v1 以降、この決まりと既存の記法は互換性を保ちます。記法を廃止・変更するときはメジャーバージョンを上げます。

スライドの区切り

--- だけの行でスライドを分けます。コードフェンス内の --- は区切りになりません。

# 1 枚目
---
# 2 枚目

ディレクティブ

スライドの 1 行目に ::...:: を置くと、そのスライドの見せ方を指定できます。 ::center bg=blue size=2:: のようにまとめて書けます。

ディレクティブ 意味
::center:: 中央寄せの大きな文字(1 枚 1 メッセージ向け)
::title:: 表紙。最後の段落はページ下に寄る
::wide:: 左右の余白を詰める(スクリーンショット向け)
::bg=blue:: 背景色。blue / orange / purple / red / green / black / white、または #rrggbb
::size=1.5:: 文字サイズの倍率

bg=white のときは自動で明るいテーマ(濃い文字色)になります。

2 カラム(::right::)

::right:: の行から右カラムが始まります。先頭の見出しはカラムの外(上)に出ます。

## 見出し
- 左に説明
- もうひとつ
::right::
```ts
const app = new Hono()
```

カラム幅は ::right left-wide::(1.4 : 1)、::right right-wide::(1 : 1.4)で変えられます。

カラムは既定で上揃えです。片側に写真のような縦に長いものを置くと、もう片側が上に詰まって見えます。 ::right center:: と書くと、そのスライドだけカラムを上下中央揃えにできます。 幅の指定と一緒に ::right right-wide center:: のようにも書けます(順番は自由)。

本文の記法

  • 見出し: # / ## / ###
  • 箇条書き: - *、番号付き 1.。インデントでネスト。
  • 太字 **太字** はアクセントカラーになる。
  • `インラインコード`、斜体、リンク [text](url)、画像 ![alt](src "caption")。
  • 引用 > 、表(| 区切り。見出し行の下に ---、:-- などで寄せを指定。セル内の | は \|)。
  • 矢印 → は少し薄く表示される。
  • -# 注釈 … 小さい注釈。

コードブロック

```ts
const x = 1
!! const y = 2 // 行頭に "!! " を付けるとその行が強調される
```

ハイライト対応: 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 は $ で始まる行をコマンド、Error や panic を含む行と make: *** で始まる行をエラーとして色分けします。

diff は + で始まる行を追加(緑)、- で始まる行を削除(赤)として行全体を塗り、 @@ の hunk ヘッダと --- / +++ のファイルヘッダも色分けします。!! も併用できます。

```diff
@@ -1,2 +1,2 @@
-const port = 3000
!! +const port = Number(process.env.PORT ?? 3000)
```

ハイライトは 1 行ずつ行うため、複数行にまたがるコメントや文字列は 2 行目以降が色分けされません。

ビルド後の HTML ではコードブロックの右上に Copy ボタンが出ます。

発表者ノート(::note::)

::note:: 以降はそのスライドの発表者ノートになります。本番スライドには表示されず、 発表者ビューやスマホリモコンだけに出ます。

本番に出る内容
::note::
ここは手元のメモ。

QR コード(::qr::)

::qr url=https://...:: と書くと、その URL の QR コードを SVG でスライドに埋め込みます。 ビルド時に生成するのでネットワークは使わず、PDF にもそのまま出ます。

::qr url=https://github.com/under18dev/ippon-slides::
::qr https://example.com caption::
  • url= は省略して URL だけを書いても構いません。
  • caption を付けると、QR の下に URL を小さく表示します(既定では出しません)。
  • 背景色(bg=)に関係なく読み取れるよう、QR は常に白地です。
  • ::right:: のカラムの中にも置けます。
  • URL は 213 バイトまでです。超えるとビルドがエラーになります。

背景画像(::background::)

::background path=img/photo.jpg:: の行を書くと、その画像をスライドの背景に敷きます。 画面いっぱいに広げ、はみ出した部分は切り取ります(object-fit: cover)。文字は画像の上に乗ります。

::center::
::background path=img/stage.jpg brightness=0.4::
# 文字を乗せる
パラメータ 意味
path= 画像のパス(Markdown からの相対パス、または URL)。path= を省いてパスだけを書いても構いません
brightness= 明るさ。1 がそのまま、0.5 で半分の暗さ。上に文字を乗せるときは 0.3〜0.5 くらいが読みやすいです
opacity= 濃さ。1 がそのまま、0 で見えなくなります。下のスライドの背景色(bg=)が透けます

::right:: より後ろに書くと、画面の右半分(右カラムの位置から右端まで、上下いっぱい)だけに敷きます。 左は文字、右は写真というレイアウトになります。left-wide / right-wide の幅にも合わせます。

## 自己紹介
- 名前
- やっていること
::right::
::background path=img/me.jpg::
  • 相対パスの画像は <img> と同じく出力先に合わせて書き換えられ、--inline で埋め込まれます。
  • 背景画像はクリックしても拡大しません。

HTTP プレイグラウンド(::http::)

::http method=GET url=https://...:: でスライド上に HTTP レスポンスを表示できます。 詳しくは HTTP プレイグラウンド を参照してください。