Zenn
✏️

claatツールを使って簡単にGoogleドキュメントでハンズオン手順を作る

2021/03/22に公開
googledocument
googlecodelabs
idea

背景

JAWS DAYS 2021のハンズオンセッションで作った手順が好評で参加者の皆さんに興味を持って頂き、作り方が知りたいという方がいたので記事にすることにしました。

Google Codelabsで公開されてるclaatツール

とても見やすいガイド付きのチュートリアルGoogle codelabsをGoogle社が公開してるのですが、なんと、この手順を簡単に作れる仕組みをGoogleさんが公開してくれていることを知り、今回のハンズオンで使わせて頂いてました。
Codelabsを作るためのツール "claat"
https://github.com/googlecodelabs/tools

この使い方を整理しましたので是非使ってみてください。

claatツールの特徴

  • GoogleドキュメントやMarkdownテキストで手順を作るだけでCodelabs形式のhtmlを生成してくれる
  • コードを記述せずにインタラクティブなWebまたはmarkdownチュートリアルを作成する機能
  • Chrome拡張プラグインで簡単にプレビューできる
  • GoogleAnalyticsによる使用状況の監視
  • ツールが公開されていて誰でも使える
  • レスポンシブ対応されていてモバイルからでも見栄えのいいチュートリアルが作れる
  • Codelabsに戻ったときに利用者が中断した場所を覚えている

完成イメージ

こんなチュートリアル手順が簡単に作れます。

チュートリアル手順イメージ

使い方

準備

環境セットアップ

ツールを使う環境の準備はこちらのReleases page.リンクをクリックし

該当するOSのリンクをクリックします。私はWindows10 64bitを使っているのでclaat-windows-amd64.exeになります。クリックするとclaat-windows-amd64.exeファイルがダウンロードされます。

一瞬だけ黒い画面であるコマンドプロンプトが起動してすぐ消えるだけでインストールできてるのかちょっと不安でしたが使えたということはこういうものなんだと思います。

claat helpコマンドが使えることを確認します。

> claat help
Usage: claat <cmd> [options] src [src ...]
Available commands are: export, serve, update, version.   

## Export command
...（長いので出力メッセージは割愛）

Go言語を使う方なら go get コマンドでもインストールできるようです。ReERishunさんの「【見やすい資料を！】マークダウンで作成できるGoogleのCodeLabを使ってみた。」ではGo getの方法で環境構築まとめられてたので参考になるかと思います。

Chrome拡張をインストール

Chrome拡張機能Preview Codelabで作成途中のGoogleドキュメントをCodelabs形式にプレビューすることができます。インストールする際にはPreview Codelabにアクセスし、[Chromeに追加]ボタンをクリックします。

Chrome拡張Preview CodelabをChromeに追加
Chromeブラウザの右上にPreview Codelabのアイコンが追加されます。

Chrome拡張アイコンが表示される

Googleドキュメントで手順を作る

Codelabsの手順作成方式としては

  • Googleドキュメントで作る
  • Markdownで作る
    の2種類ありますが、私はGoogleドキュメントを使っています。

こちらのGoogleドキュメントを参考にして手順を作成してください。

Preview Codelabで手順をプレビューする

Googleドキュメントを開いている状態で、Preview CodelabのChrome拡張ボタンをクリックします

Preview CodelabのChrome拡張ボタンをクリック
別タブでプレビュー画面が開きます。プレビューでの見え方をチェックしながら手順を修正できます。

プレビュー画面イメージ

GoogleドキュメントからCodelabのソースを生成する

GoogleドキュメントのURLは https://docs.google.com/document/d/xxxxxxxxxxxx/edit# という形式になっているかと思います。

このxxxxxxxxxxxの部分をメモしておき、Codelab形式のソースを出力したいフォルダで以下のコマンドを投入し、ok のメッセージが出力されることを確認します。

> claat export xxxxxxxxxxxxxxxxxxxxxxxxx
ok      codelabs-tool

コマンドを投入したフォルダ直下に、Googleドキュメントの表のURLに指定した名前でフォルダが作成され、

以下の構成でファイルが生成されます。

\codelabs-tool
|   codelab.json
|   index.html
|   README.md
|
\---img
        19596b6d87dc52d1.png
        1d84bd463425aba7.png
        ...

Webへの公開

これを以下のようなWebページに公開すればインターネット経由で外部から見える状態になります。

  • Github Pages（*.github.io）
  • Google App Engine
  • Firebase静的サービング
  • Google Cloud Storage
  • AWS S3
  • Netlify
  • オープンソースのWebサーバー（Nginx、Apache）
  • python -m SimpleHTTPServer （Python 2）
  • python3 -m http.server （Python 3）

Github PagesでのWeb公開

今回はGithubに公開します。
まずは先ほど生成したCodelab形式のソースをGithubにプッシュしたリポジトリのSettingsをクリックします。

Githug Pagesの項目でSelect branchでmainを選択しSaveすると

できました。このURLがCodelabs形式で公開したハンズオン手順のページです。

完成

完成イメージとそれを作成した時のGoogleドキュメントを公開してますので参考になれば幸いです。
※Googleドキュメントは編集不可のリンクで共有していますので、編集して使いたい時には編集権限リクエストするのではなく、ファイル＞コピーを作成 で自分のGoogleドキュメントにコピーして編集して使ってください。

参考になった情報

Discussion