Markdown 記法
ippon は手書きの Markdown サブセットパーサーです。普通の Markdown に、スライド向けの 記法を少し足したものと考えてください。
frontmatter
ファイル先頭に key: value だけの簡単な frontmatter を書けます。
---title: 発表タイトルauthor: あなたの名前description: 説明(任意)lang: jaurl: 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::
```tsconst app = new Hono()```カラム幅は ::right left-wide::(1.4 : 1)、::right right-wide::(1 : 1.4)で変えられます。
カラムは既定で上揃えです。片側に写真のような縦に長いものを置くと、もう片側が上に詰まって見えます。
::right center:: と書くと、そのスライドだけカラムを上下中央揃えにできます。
幅の指定と一緒に ::right right-wide center:: のようにも書けます(順番は自由)。
本文の記法
- 見出し:
#/##/### - 箇条書き:
-*、番号付き1.。インデントでネスト。 - 太字
**太字**はアクセントカラーになる。 `インラインコード`、斜体、リンク[text](url)、画像。- 引用
>、表(|区切り。見出し行の下に---、:--などで寄せを指定。セル内の|は\|)。 - 矢印
→は少し薄く表示される。 -# 注釈… 小さい注釈。
コードブロック
```tsconst 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 プレイグラウンド を参照してください。