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

Microsoft MakeCode には、チュートリアル機能があり、チュートリアル作成ツールで独自のチュートリアルを作成することができます。
もちろん、micro:bit向けのチュートリアルの作成も可能です。

チュートリアル作成ツール（turorial-tool）

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

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

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

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

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

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

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

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

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

チュートリアル例

# 独自チュートリアル

## 第1ステップ

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

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

## 第2ステップ

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

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

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

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

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

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

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

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

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

チュートリアルの追加

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

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

README.mdの編集

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

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

README.md

...

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

...

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>

チュートリアルを開始できないとき

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

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

pxt.json

    "targetVersions": {
        "target": "6.0.25",
        "targetId": "microbit"
    },

多言語対応

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

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

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マクロの記述方法

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

neopixelの例

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>