【( ..)φメモメモ】micro:bitチュートリアルの作り方 (MakeCode)

# チュートリアル作成ツール

Microsoft MakeCode には、チュートリアル機能があり、[チュートリアル作成ツール](https://makecode.com/tutorial-tool)で独自のチュートリアルを作成することができます。
もちろん、micro:bit向けのチュートリアルの作成も可能です。

[**チュートリアル作成ツール（turorial-tool）**](https://makecode.com/tutorial-tool)

https://makecode.com/tutorial-tool

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/252891/a69701e0-9d65-5704-f772-26ff08924baf.png)

# 独自チュートリアルの作成方法

チュートリアルの作成方法は次のページで紹介されています（一部、日本語訳あり）。

https://makecode.com/writing-docs/tutorials

# チュートリアルのチュートリアル

次の参考動画を元に、実際にチュートリアルを作成してみます。

**参考動画（英語）**- 30分の動画で、チュートリアルの基本を学べます。

https://youtu.be/R-kY-dQXZvA

## チュートリアル作成ツールの使い方

次の手順でチュートリアルを作成することができます。

1. チュートリアル作成ツールを開く
→ https://makecode.com/tutorial-tool
1. エディターで `micro:bit` を選ぶ
1. 見出しレベル2（`##`）にチュートリアルのステップを記述する
1. `blocks` セクションにソースコードを記述する
1. `RUN`ボタンで、チュートリアルを試す
1. `共有`ボタンで、チュートリアルを共有する（URLの生成）

`共有`ボタンで生成されたURLへアクセスすると、Microsoft MakeCode for micro:bitが開き、チュートリアルが開始されます。


````md:チュートリアル例
# 独自チュートリアル

## 第1ステップ

ここに説明を記述します。  
（電球のヒントアイコンで、`blocks`を表示できます）

```blocks
basic.showString("Hello!")
```

## 第2ステップ

素晴らしい！！  
完成です！  

````

## MakeCode上で作成する方法（GitHub連携）

GitHubと連携させて、Microsoft MakeCode for micro:bit上で、チュートリアルを作成することができます。チュートリアルの内容は、Markdown形式ファイルに記述します(例えば、`tutorial.md`)。

**プロジェクトの作成とGitHub連携**

プロジェクトを新規作成し、GitHubと連携します。

1. Microsoft MakeCode for micro:bit を開く
→ https://makecode.microbit.org/
1. プロジェクトを新規作成する
プロジェクト名：`smiley-frowney`
1. GitHubリポジトリを作成する（GitHubアイコンボタン）

**プロジェクトファイルの準備**

JavaScriptエディタで、プロジェクトファイルを操作します。

1. JavaScriptエディタに変更する
1. `main.blocks`を削除する
1. `main.ts`の内容を空にする（残したまま）
1. GitHubにプッシュする


**チュートリアルの追加**

ファイル名を`tutorial.md`として、チュートリアルを追加します。

1. エクスプローラーの+ボタンでファイルを追加する
1. ファイル名を`tutorial.md`とする
1. チュートリアル作成ツール上で作成した内容を`tutorial.md`にコピーする
1. 右側の`＜`タブで、ドキュメントとしてプレビューできる
1. エクスプローラーの`プレビュー`アイコンでチュートリアルをテストする
1. GitHubにプッシュする


## README.mdの編集

README.mdをランディングページとし、ここからチュートリアルへリンクさせます。

1. MakeCode上で`README.md`を開き、`tutorial.md`のドキュメントページへリンクする(`/smiley-frowney/tutorial`)
1. `tutorial.md`をドキュメントページとして開いた際に、コードをブロック形式で表示する為に、ファイルの末尾にスクリプトを追記する
1. `tutorial.md`横の`共有`アイコンでチュートリアルのURLを生成する
1. 生成したURLへリンクする（`https://makecode.microbit.org/#tutorial:github:<your github account>/smiley-frowney/tutorial`）

````md: README.md
...

* [チュートリアル](/smiley-frowney/tutorial) [開始](https://makecode.microbit.org/#tutorial:github:<your github account>/smiley-frowney/tutorial)

...
````

````md: tutorial.md
...

<script src="https://makecode.com/gh-pages-embed.js"></script><script>makeCodeRender("{{ site.makecode.home_url }}", "{{ site.github.owner_name }}/{{ site.github.repository_name }}");</script>

````

:::note warn
**チュートリアルを開始できないとき**

`共有`アイコンで生成したURLにアクセスしても、チュートリアルを開始できなず、次のようなエラーメッセージが表示されることがあります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/252891/28905496-6a2f-ccb4-fce7-5b4ba4303a65.png)

GitHub上で、pxt.jsonの`target`を少し古いバージョンにするとチュートリアルを開始できるようになるかもしれません。

```json:pxt.json
    "targetVersions": {
        "target": "6.0.25",
        "targetId": "microbit"
    },
```

:::


## 多言語対応

作成したチュートリアルを多言語対応することが可能です。
日本語(`ja`)のチュートリアルは、ローカライズされた`_locales/ja/tutorial.md`ファイルに記述します。元の`tutorial.md`ファイルの内容は、英語で記述します。

1. MakeCodeの設定で、言語を「日本語」にする
1. MakeCodeのエクスプローラーで、`tutorial.md`の地球儀アイコンでローカライズされたファイルを追加する
1. 追加された`_locales/ja`フォルダ内の`turorial.md`を開く
1. `_locales/ja/tutorial.md`ファイルの内容を日本語で記述する
1. `tutorial.md`ファイルの内容を英語で記述する
1. GitHubにプッシュする
1. `ページを開く`でGitHubページを開き、`開始`リンクでチュートリアルを開始する
1. MakeCodeの設定で、言語を「日本語」にするとチュートリアルも日本語になり、「日本語」以外にするとチュートリアルは、英語になる

````md: tutorial.md
# My Tutorial

## Step 1

Here is some text.

```blocks
basic.showString("Hello!")
```

## Step 2

Congratulations, you did it!

<script src="https://makecode.com/gh-pages-embed.js"></script><script>makeCodeRender("{{ site.makecode.home_url }}", "{{ site.github.owner_name }}/{{ site.github.repository_name }}");</script>

````

# 拡張機能のチュートリアル

拡張機能（extensions）を含むチュートリアルを作成する場合、その拡張機能のGitHubリポジトリ情報を`package`マクロで記述します。また、`README.md`等のGitHubページで、拡張機能のブロックを表示するために、「拡張機能の表示方法（非公式）」に従って、末尾のscriptの記述を変更します。

**packageマクロの記述方法**

https://makecode.com/writing-docs/snippets#package

**拡張機能の表示方法（非公式）**

https://qiita.com/jp-96/items/0c9ebd824a5ebb26e7ae#%E6%8B%A1%E5%BC%B5%E6%A9%9F%E8%83%BD%E3%81%AE%E8%A1%A8%E7%A4%BA%E6%96%B9%E6%B3%95%E9%9D%9E%E5%85%AC%E5%BC%8F

## neopixelの例



````md: tutrial.md
# My Tutorial

```package
neopixel=github:microsoft/pxt-neopixel
```

## Step 1

Here is some text.


```blocks
let strip = neopixel.create(DigitalPin.P0, 24, NeoPixelMode.RGB)
strip.setPixelColor(0, NeoPixelColors.White)

```

## Step 2

Congratulations, you did it!

<script src="https://cdn.jsdelivr.net/gh/jp-rad/pxt-ubit-extension@0.5.0/.github/statics/gh-pages-embed.js"></script><script>makeCodeRender("{{ site.makecode.home_url }}", ["neopixel=github:microsoft/pxt-neopixel",]);</script>

````