[入門]誰でも簡単にできるKatacodaで学習コンテンツを公開するまで

概要

Katacodaはブラウザで完結する学習プラットフォームです。
技術系の学習で煩わしかった環境構築を無したことで、学びに対するハードルをぐっと下げることができるのがメリットです。
今回は学習するためのKatacodaではなく、学習してもらうためのコンテンツを作成するためのKatacodaについて紹介したいと思います。
一応公式のチュートリアルもありますが、わかりづらかったので改めて紹介します。

Katacodaのコンテンツはクリックするだけで学べるという気軽さもあるが、一方で学習効果に疑問を感じている方いるいます。すぐに学びたいという方や初心者向け、内容が難しいものを学習するのには向いているプラットフォームかなと思います。また、学習内容がコード化されることで「Learn as a Code」（勝手に作りましたｗ）も一つのメリットかなと思います。

個人的に向いている理由の詳細

• すぐに学びたい方
  • 環境構築をしなくてもいい
  • 何かの動作を比較したい時にはいい
• 初心者向け
  • 環境準備をしなくてもいい
  • そもそも何もわからないのに環境構築で挫折しなくても済む
• 内容が難しいもの
  • 環境に依存しない正しい動作をすぐに確認できる
  • 難しい周辺のことを置いといてすぐに学べられる。例えば（昔は）Kubernetesの環境準備だけでも大変

必要なもの

コンテンツを作るのに必要なものは以下になります。

• Node.js
• Git
• Katacoda CLI
• Githubのアカウント(無料枠でOK)
• Katacodaのアカウント
• テキストエディタ
  • VSCodeにKatacodaの拡張機能もあります

VSCodeのRemote Developmentの実行環境もありますので、併せてご利用ください。

コンテンツの構成

学習テーマを「コース」(course)、その中で学習するための章を「シナリオ」(scenario)と呼ぶ。
章の中の「ステップ」が学習単位になります。コンテンツの内容はMarkdown記法で記載する。
後述のシンタックスを活用することで、コンテンツ内のコマンドをクリックして、自動でコマンドを実行してくれたりします。

コース
 |
 | - シナリオ1
       |
       | - イントロ(intro.md)
       | - ステップ1(step1.md)
       | - ステップ2(step2.md)
       | - ステップ3(step3.md)
       | - まとめ(finish.md)
 | - シナリオ2
 | - シナリオ3
       :
       :
     シナリオn

手順

ざっくり３ステップ！

• コース(course)を作る
• シナリオ(scenario)を作る
• 公開する

なお、Node.jsとGitのインストール、Github、Katacodaのアカウント取得は割愛します。

1. katacodaコマンドを導入

katacodaコマンドをグローバルインストールすることで使用できるようにする
参照：コマンドのリファレンス

> npm install katacoda-cli --global

※Dockerコンテナを使用したVSCodeのRemote Developmentの実行環境もありますので、併せてご利用ください。

2. コース(course)を作成

> katacoda courses:create

以下のように対話形式でコース名、説明などを入力します。
入力後にコースに関連するシナリオを格納するためのフォルダと<コース名>-pathway.jsonが作成されます。
もし、作成後にコース名や説明を修正したい場合は、xxx-pathway.jsonを直接編集すればOK。

# コース名(日本語もOK)
? Course Title:  My First courses

# コースの説明(日本語もOK)
? Course Description:  Sample katacoda course

# コースのフォルダ名
? friendly-url (This will also be the course's folder name):  SampleKatacodaCourse
Course created successfully.

3. シナリオを作成

> katacoda scenarios:create

以下のように対話形式でシナリオ名、説明、対象者などを入力します
実行環境(Ubuntu、Docker、k8s)はコンテンツに合わせて選択してください

# シナリオのフォルダ名
# シナリオはコースに比べて多くなるので、下記のようにscenariosフォルダにまとめることもできます
# ただし、コマンド実行前に予めフォルダを作成すること
? Friendly url:  scenarios/SampleScenario

# シナリオ名
? Scenario Title:  Sample Scenario

# シナリオ説明
? Scenario Description:  Sample Scenario

# 対象者レベル
? Difficulty Level:  Beginner

# 所要時間
? Estimated time: (Please specify in minutes or hours e.g. 2 hours) 5m

# ステップ数
? Number of Steps (Not including intro & finish):  5

# 実行環境
# https://www.katacoda.com/docs/scenarios/environments
# いくつかのバージョンが選べます
? Image:  Ubuntu 19.04

# ターミナル（コンソール）の種別
? Layout:  Terminal

上記で選択した内容がindex.jsonに記載されます。
詳しい説明はこちらを参照ください。

scenarios/SampleScenario/index.json

{
  "title": "Sample Scenario",
  "description": "sample scenario ",
  "difficulty": "Beginner",
  "time": "5m",
  "details": {
    "steps": [
      {
        "title": "Step 1",
        "text": "step1.md"
      },
      {
        "title": "Step 2",
        "text": "step2.md"
      },
      {
        "title": "Step 3",
        "text": "step3.md"
      },
      {
        "title": "Step 4",
        "text": "step4.md"
      },
      {
        "title": "Step 5",
        "text": "step5.md"
      }
    ],
    "intro": {
      "text": "intro.md"
    },
    "finish": {
      "text": "finish.md"
    }
  },
  "environment": {
    "uilayout": "terminal"
  },
  "backend": {
    "imageid": "ubuntu1904"
  }
}

4. コンテンツの作成

前述でシナリオされたstepX.mdにMarkdown形式で学習手順を記載していきます。

• Katacoda内で使用できるシンタックスを利用することでコンテンツの利便性を向上させることが可能。
  VSCodeの拡張機能を導入するとシンタックスの入力もしやすくなります。
• コンテンツ内でWebサーバを公開するような場合は、こちらを参照ください

5. シナリオとコースの関連付け

シナリオを作成したら、コースと関連します。
Katacodaではシナリオの再利用性できるような仕組みが予め用意されています。

> katacoda courses:add:scenarios

以下のように対話形式でシナリオパスとコースパスなどを入力します。

# 対象のシナリオまでのファイルパス
? Please enter scenario path: scenarios/SampleScenario

# 対象のコースまでのファイルパス
? Please enter course path: SampleKatacodaCourse

# 関連付け方法
# CopyとMoveが選べます
# Copy･･･シナリオがコースにそのままコピーされる
# Move･･･シナリオがコースに移動される
? Would you like todo? Copy to courses folder

関連付けした後はxxx-pathway.jsonに以下の様に関連付け情報が記載されます。
慣れている人ならば、コマンドじゃなく直でjsonを編集しちゃってもいいかと思います。

SampleKatacodaCourse-pathway.json

{
  "title": "My First courses",
  "description": "Sample katacoda course",
  "courses": [
    {
      "course_id": "SampleScenario",
      "title": "Sample Scenario",
      "description": "sample scenario "
    }
  ]
}

6. 公開

予めGithubのアカウントが必要になりますので、未取得の場合はこちらで取得しましょう！
あとこちらに従って設定することで公開できる

上記の手順にない以下の設定も必要です

• Webhookの設定で「Content type」を「application/json」に変更して、保存
• KatacodaのプロフィールのName、Usernameを入力するとアカウントとGithubの連携が開始されます（すぐに連携したい場合は、下記の手動同期を実行してください）
  ※作成後はUsernameの変更はできません！変更したい場合は、一度アカウント削除してから再作成になります。
  ※KatakodaとGithubの連携は1つのリポジトリのみが対象になります。1つのリポジトリですべてのコースを管理しなければならない（ちょっとイケてない）

手動同期

同期後はこんな感じになります

手順は以上になります。
まだ、使い始めたばっかりなので、今後は使い方編（あれば）を書いてみたいと思います。