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

# 概要

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

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

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

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

# 必要なもの

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

- Node.js
- Git
- [Katacoda CLI](https://www.katacoda.com/cli)
- [Githubのアカウント](https://github.com/join)(無料枠でOK)
- [Katacodaのアカウント](https://www.katacoda.com/signup)
- テキストエディタ
    - VSCodeに[Katacodaの拡張機能](https://marketplace.visualstudio.com/items?itemName=Katacoda.vscode)もあります

[VSCodeのRemote Developmentの実行環境](https://github.com/comefigo/katacoda-courses/tree/master/.devcontainer)もありますので、併せてご利用ください。

# コンテンツの構成

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

```text
コース
 |
 | - シナリオ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コマンド](https://www.npmjs.com/package/katacoda-cli)をグローバルインストールすることで使用できるようにする
参照：[コマンドのリファレンス](https://www.npmjs.com/package/katacoda-cli)

```shell:
> npm install katacoda-cli --global
```

※Dockerコンテナを使用した[VSCodeのRemote Developmentの実行環境](https://github.com/comefigo/katacoda-courses/tree/master/.devcontainer)もありますので、併せてご利用ください。

## 2. コース(course)を作成

```shell
> 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. シナリオを作成

```shell
> katacoda scenarios:create
```

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


```shell

# シナリオのフォルダ名
# シナリオはコースに比べて多くなるので、下記のように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`に記載されます。
詳しい説明は[こちら](https://www.katacoda.com/docs/scenarios/index-json)を参照ください。

```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内で使用できる[シンタックス](https://www.katacoda.com/docs/scenarios/markdown-syntax)を利用することでコンテンツの利便性を向上させることが可能。  
    [VSCodeの拡張機能](https://marketplace.visualstudio.com/items?itemName=Katacoda.vscode)を導入するとシンタックスの入力もしやすくなります。
![katacoda_run_command.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/30522/c76e1d62-ce93-f653-0f66-be0b53762521.png)
- コンテンツ内でWebサーバを公開するような場合は、[こちら](https://www.katacoda.com/docs/scenarios/displaying-ports)を参照ください



# 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を編集しちゃってもいいかと思います。

```json:SampleKatacodaCourse-pathway.json
{
  "title": "My First courses",
  "description": "Sample katacoda course",
  "courses": [
    {
      "course_id": "SampleScenario",
      "title": "Sample Scenario",
      "description": "sample scenario "
    }
  ]
}
```

# 6. 公開

予めGithubのアカウントが必要になりますので、未取得の場合はこちらで取得しましょう！
あと[こちらに従って設定](https://katacoda.com/docs/configure-git)することで公開できる

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

- Webhookの設定で「Content type」を「**application/json**」に変更して、保存
- KatacodaのプロフィールのName、Usernameを入力するとアカウントとGithubの連携が開始されます（すぐに連携したい場合は、下記の[手動同期](#手動同期)を実行してください）  
    ※作成後はUsernameの変更はできません！変更したい場合は、一度アカウント削除してから再作成になります。  
    **※KatakodaとGithubの連携は1つのリポジトリのみが対象になります。1つのリポジトリですべてのコースを管理しなければならない（ちょっとイケてない）**
![create_profile.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/30522/b0732dc6-f38b-9881-2a62-180339ffde56.png)

## 手動同期
![Katacoda_trigger_repo.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/30522/7bfeacc9-4c46-c1a6-ce97-6f3a34aca34c.png)


同期後はこんな感じになります
![katacoda_profile.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/30522/9adfc690-7cc3-47fd-375d-755846a09144.png)


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