【見やすい資料を！】マークダウンで作成できるGoogleのCodeLabを使ってみた。
Google CodeLabを利用して読みやすい資料を作成する
先日、MarkingCloudさんのハンズオンに参加したのですが、資料がとても分かり易く（勿論ハンズオン自体も丁寧で分かり易く）、感動しました...
話を聞いてみるとGoogle CodeLabで作ったとのことで、私も真似したくなったため、今回実際に作ってみました！
実際にできるもの
この記事を読むとこちらのような資料を作ることが出来ます！
CodeLabの紹介
ちなみに、こちらのリポジトリは以下になるので、何か実際に書いてみて分からない点等ありましたら、参考までにご覧ください。
ree-rishun/codelab-zenn - GitHub
この記事の流れ
本記事では以下の流れで環境構築から実際に公開するまでを紹介します。
- 環境構築
- ファイル作成
- 書き方
- HTMLへエクスポート
- GitHubPagesで公開
環境構築
環境構築には、Goとclaat（codelabsコマンドラインツール）をインストールする必要があります。
Goのインストール（Macの場合）
Windowsユーザなので、ここはCodeLabの内容をほぼコピペ。
インストール
$ brew install go
PATHを通す
$ export GOPATH=$HOME/Go
$ export GOROOT=/usr/local/opt/go/libexec
$ export PATH=$PATH:$GOPATH/bin
$ export PATH=$PATH:$GOROOT/bin
Goのインストール（Windowsの場合）
WindowsのGoの環境構築に関しては、私のブログで画像付きで解説しているので
【Go言語】Windowsでの環境構築から基礎編 - MakerBlog
claatのインストール（両OS共通）
$ go get -u -v -x github.com/googlecodelabs/tools/claat
確認
$ claat -h
これでhelpが表示されたら完了です！
作ってみる。
CodeLabの作り方は2つあります。
- Googleドキュメントを使っての作成
- Markdownを使っての作成
今回は、みんな大好きマークダウンを使って書いていきます。
ファイル作成
まずはマークダウンファイルを作ります。名前は何でもいいです（全角でもいいのかは不明）
※注意点：（特にWindowsの方は）改行コードは必ず「LF」に設定してください。
この設定を忘れると、改行を認識してくれないため記述通りに表示されなくなります。
ファイルを作成したら、頭に以下の内容を記述します。
author: 作成者名
summary: 説明文
id: 一意のIDを自分で定義
categories: codelab,markdown
environments: Web
status: ステータスを指定
feedback link: 利用者がフィードバックを送る先（Gitリポジトリが推奨みたいです。）
analytics account: Google Analytics ID
ステータスの部分は以下のパラメータを指定できます。
- Draft: 下書き状態
- Published: 公開
- Deprecated: 非推奨（記事の内容が古いってことを表していると解釈しています…）
- Hidden: 非公開
試しに指定して見ると以下のようになります。
author: ReERishun
summary: CodeLabの解説用
id: codelab-test-markdown
categories: codelab,markdown
environments: Web
status: Published
feedback link: https://github.com/ree-rishun/codelab-test
analytics account: XXXXXXXX
そして、タイトルは見出し１で表記します。
# CodeLabの紹介
セッションごとの区切り
セッションは見出し２で区切ります。
## はじめに
Duration: 0:05:00
セッションの見出しの下に書いたDurationはこのセッションを読むためにかかる時間を記載しています。
基本はマークダウンで書けます
あとは、基本的にマークダウンです。
見出し１と見出し２はそれぞれページタイトル、セッションタイトルという意味合いを持つので、セッション内で見出しを付けたい時は見出し３以下を利用してください。
### 途中の見出し
他には、以下のようなマークダウンが可能です。
- リスト１
- リスト２
- リスト３
* リストA
* リストB
* リストC
[リンク](https://www.google.com/)
**太字**
*Italic*（斜体）
~~取り消し線~~
画像の挿入
画像も、通常の画像ファイルと同じように書くことが出来ます。
ちなみに、ローカルの画像のパスも指定できます。
その場合、エクスポート後のフォルダに画像がコピーされます（ネット上の画像のリンクを指定した場合は引き続きリンクが表示されます。）
CodeLab特有の記述
通常のマークダウンの他に対応しているHTMLタグもあります！
ダウンロードボタン
ダウンロードボタンという名目ですが、リンクへ飛ばす用のボタンとしても利用可能です。
<button>
[ボタンリンク](https://zenn.dev/reerishun/articles/ac128b86e090195f59cd/)
</button>
実際に表示されるとこのような感じになります。
お知らせボックス
目立たせたい情報を表示する際に使います。
Positive
: 何かお知らせを書きたい時のボックス
Negative
: 何か注意点などを書きたい時のボックス
それぞれ、実際にはこのようになります。
詳しくはサンプルコードを…
他にもコードの埋め込みや、テーブルなども実現可能です。
冒頭で紹介したサンプルコードのリポジトリを見て頂ければ、サンプルコードに含まれているコンテンツの書き方が分かりますので、是非覗いてみてください。
ree-rishun/codelab-zenn - GitHub
CodeLabのマークダウンに関して更に詳しく知りたい方は、こちらのREADMEをご覧ください。
googlecodelabs/tools/claat/parser/md/ - GitHub
エクスポート
ここでやっと最初の環境構築でインストールした、claatが役に立ちます。
コマンドラインで、以下を実行することでエクスポートできます。
$ claat export <マークダウンファイル名>
例えば、codelab.mdというファイルで作成した場合は以下のように実行します。
$ claat export codelab.md
すると、実行したディレクトリに指定したID名のフォルダが生成されます。
例えば、私の場合は以下のようになります。
|―― /codelab-id（自身の設定したID）
| |―― index.html
| |―― codelab.json
| |―― /img （画像ファイルを扱ってる場合）
|―― codelab.md（自身の作成したcodelab用のマークダウン）
このように表示されればOKです。index.htmlを開いてみると、できているかと思います。
※ローカルで開くと読み込みに毎度時間がかかります。
GitHub Pagesでの公開
GitHubのリポジトリへプッシュした前提で話をしていきます。
まずは、右側にあるリポジトリのSettingを開きます。
続いて、GitHub Pagesの項目まで下にスクロールします。
その後、特に理由がなければ
- Branch : master
- directory : /root
に設定し、「Save」ボタンを押します。
開いて確認
通常、https://<userID>.github.io/<repository>がリポジトリ直下に設定されるのですが、マークダウンと一緒にアップロードした場合は、リポジトリ内が以下のようなディレクトリ構造になっているかと思います。
|―― /codelab-id（自身の設定したID）
| |―― index.html
| |―― codelab.json
| |―― /img （画像ファイルを扱ってる場合）
|―― codelab.md（自身の作成したcodelab用のマークダウン）
この場合https://<userID>.github.io/<repository>/<codelab-id>とすると開きます。
最後に
初めて資料を読んだときはとても見やすく、今後ハンズオン等を開催する際に利用しようと思いました。他にも、ドキュメントとして利用したり、自身のノートとしても後で見返しやすいと思いました。
是非、皆さんも利用してみてください！
参考元
googlecodelabs/tools - GitHub
googlecodelabs/tools/claat/parser/md/ - GitHub
今回のブログ曲
今回投稿中に聴いていた曲はこちら
Discussion