reveal.js + Markdown + GitHub Pagesでスライド公開

久しぶりに触ってみたら色々便利になってたので。（個別では記事が散見されるものの、まとまったものが意外となかったので書いとく）

## TL;DR
- `reveal-ck` 使うとマークダウンでスライド作るの捗る
- GitHub Pagesの公開までがやたら簡単になってた

## reveal.js
HTML+CSS+jsでスライドを作れるライブラリ。かなり前からあるので、触ったことある人も多いと思います。

用意されてるテーマやアニメーションも豊富で作成も簡単。そこまで作り込まないスライドならこれで十分なはず。

[reveal.js](https://revealjs.com/#/)

※基本的な使い方は割愛。[README](https://github.com/hakimel/reveal.js/)読めば大体わかる。

### reveal-ckを使ってマークダウン連携を捗らせる
`reveal.js` 単体でも、HTML内に埋め込むことでマークダウンを使用することができるのですが、

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Page Title</title>
</head>
<body>
  
<section data-markdown>
  <textarea data-template>
    ## Page title
  
    A paragraph with some text and a [link](http://hakim.se).
  </textarea>
</section>

</body>
</html>
```

こんなかんじ。なんか、嫌じゃ・・・ないですか・・・・？※マークダウンでシンプルに書きたいのにHTMLタグ出てくるし、もともとあったマークダウンファイルの流用できない（コピペしてこなきゃいけない）し・・・。

そこで、 `reveal-ck` です。

[reveal-ck](http://jedcn.github.io/reveal-ck/)

公式サイトにも、

> Create a reveal.js presentation from a single file.
> Write slides in markdown.
> Create a presentation with one command.
> Learn advanced features only when you need them.

と書かれている通り、とにかく機能がシンプル。且つ、必要になったときの拡張性にも優れているので良さがあります。

## 導入
（Mac環境を想定していますが、 `ruby` 入っていれば大体いけるかと思います（未検証））

`gem` で入れていきます。

```bash
$ ruby -v
ruby 2.5.2p104 (2018-10-18 revision 65133) [x86_64-darwin18]
$ sudo gem install reveal-ck
.....
```

一応確認。

```bash
$ reveal-ck -v
reveal-ck version 3.9.0
```

いけましたね。

## スライドの作成
`reveal-ck` は基本的に1枚のマークダウンファイルから、スライドを生成していくことになります。

やっていきます。

```bash
$ mkdir your_slide_dir
$ cd your_slide_dir
$ touch slides.md
```

作成した `slides.md` に適宜内容を追加してスライドを生成してみます。

```bash
$ echo "# This is Slide" >> slides.md
$ reveal-ck generate
```

これだけで、スライドが生成されています。※カレントディレクトリの直下に `slides/` というディレクトリが吐き出されます。

一応確認してみます。

```bash
$ ls
slides    slides.md
$ open slides/index.html
```

いけてそうですね。

ちなみに、マークダウンファイルの名前は `slides.*` である必要があるので、それ以外のファイル名で生成しようとすると怒られます。

```bash
# 駄目な例
$ touch index.md
$ reveal-ck generate

Problem:

  reveal-ck could not find a slides file, and it cannnot build
  your presentation without one.

  It thinks anything that matches "slides.*" is a slides file.

  Some examples are: slides.md, slides.html, slides.haml

error: Create a file matching slides.* to proceed, such as slides.md.
```

## 基本的な書式と設定
さて、先程までの操作でマークダウン→スライドの生成はできましたが、このままではペライチのHTMLが生成されただけなので、何もおもしろくありません。実際にスライドを作っていきます。

とはいえ、必須で覚えるべきなのはスライドのページ分割記法くらい。あとは、マークダウンの記法と設定の仕方になりますが、一旦置いておいて、見ていきます。

[Slides with Markdown - reveal-ck](http://jedcn.github.io/reveal-ck/markdown/)

まず、作成しながら表示確認をするためにサーバを立ち上げます。

```bash
$ reveal-ck serve
------------------------------------------------------------
[ reveal-ck ] Serving up slide content in 'slides/'.
[ reveal-ck ] Open your browser to 'http://localhost:10000'.
[ reveal-ck ] Press CTRL-C to stop.
------------------------------------------------------------
```

デフォルトで `localhost:10000` に立つので、ブラウザで開きましょう。この状態だと編集し保存するたびに自動リロードしてくれます。

以下、あくまでサンプルなので、内容はないですが。

```markdown:slides.md
# This is Slide
Slide page 1.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. 

- Morbi
- orci
- lorem

[example.com](http://example.com/)

---

## This is page 2

***

## This is first vertical

---

## Second vertical

---

## Third vertical

***

## Next horizontal
```

基本的にページ分割は `---` です。 `***` で分割すると、そこから次の `***` が出てくるまでは、縦方向にスライドしてくれます（便利）。

※縦方向にスライドする意義としては、「なんとなく格好いい」以外に「特定の情報のまとまりとして分けたい」などの時に使用するといいかと思います。「格好いいのは大事」なので適当に縦方向に行っても別に問題はないと思いますが。

また、スライド全般に渡る設定については、プロジェクトルートに `config.yml` を置くことで適用出来ます。

```bash
$ cd your_slide_dir
$ touch config.yml
$ vi config.yml #色々設定を書く
```

以下、簡単な設定例（公式サイトから引用）です。

```yaml:config.yml
theme: "night" #テーマ設定
transition: "page" #スライドの挙動設定
title: "My Presentation!" #スライドのタイトル。<title>に設定されます。
revealjs_config: #以下、reveal.js用の個別設定（厳密には上の、themeもtransitionもreveal.jsの設定です）
  autoSlide: 5000
  loop: true
```

`reveal.js` で使える設定項目に関しては、公式に詳細な記述があるので、確認してください。

[reveal.js - Configuration](https://github.com/hakimel/reveal.js/#configuration)

## GitHub Pagesへの公開
スライド作成後に他の人にも共有したい場合、自分のマシンをつないでローカルを見せるとか、PDFにして配布などもありますが、GitHub Pagesにホスティングしておくとはかどります。※しかも簡単。

やっていきます。

```bash
$ cd your_slide_dir
$ reveal-ck generate
```

GitHub上に適当にリポジトリ作ります。（GitHubの説明は割愛）


```bash
$ git init
$ echo "slides/" > .gitignore
$ git remote add origin https://github.com/your_account_name/your_repository_name.git
$ git add --all
$ git commit -m "initial commit"
$ git push --set-upstream origin master
```

次にGitHub Pages用にブランチを切って、公開作業をします。

（2019.03.14修正 https://sue445.hatenablog.com/entry/2015/10/03/201241 読み直していたら、スマートなやり方をおすすめされていたので、コマンドまるまる削除して、引用に変更。 参考： https://github.com/jedcn/reveal-ck/wiki/Publishing-Slides ←公式に記述があるらしくて、上の記事の人も書いているけど、まさに「そういうやり方があったのかー！」です）

> - masterブランチの .gitignore に slides/ を登録
> - git checkout --orphan gh-pages で親commitがないgh-pagesブランチを作成。
> - git commit --allow-empty で空コミット作ってpush
> - git clone <git url> --branch gh-pages --single-branch ./slides でslides配下にgh-pagesのみをclone
> - reveal-ck generate でslides/ ファイルを作成
> - cd slides して commit & push したらそれがgh-pagesに反映される

（引用元： https://sue445.hatenablog.com/entry/2015/10/03/201241 ）

これで、 `https://your_account_name.github.io/your_repository_name/` にアクセスすれば、先程作成したスライドが確認出来るはず。

以上になります。

## 追記 - ちょっとしたjs書きたいとき
公式のドキュメント追っかけてみても記述が見つからなかったんですが、マークダウン中でも `<script>` タグ埋め込めば、実行される感じでした。

```markdown:sample
## some title
hogehoge hogehoge

---

## some title
fugafuga fugafuga

<script>
document.querySelectorAll('a').forEach(e => e.target = '_blank');
</script>
```

上の例は、リンクを常に別タブで開くようにする。デフォルトだと同一タブ内に開いてしまうので。
注意点としては、マークダウンファイルの末尾に追加することと、 `<script>` タグ前にページ分割（ `---` ）を置かないこと（置くと空のスライドが追加されちゃいます）。
良い感じですね。

### おまけ：PDFに生成する場合
URLに `?print-pdf` を付与してアクセスして、ブラウザからPDFで印刷すればOK。ただし、アニメーションや縦方向のスライドは効かないです。

※また、私が試した際は、 `https://your_account_name.github.io/your_repository_name/slides/index.html?print-pdf` のような形式でアクセスする必要がありました。
※ローカルの場合、 `http://localhost:10000/?print-pdf` で行けたのでそちらのほうが簡単かもです。