Cloud Shell のチュートリアルの作成

Cloud Shell は、ユーザーがプロジェクトに迅速かつ効果的に慣れるためのチュートリアルの作成と起動に対応しています。

チュートリアルは、Markdown で記述された一連の手順です。Cloud Shell は、テキストをステップとサブステップに解析することにより、これらの Markdown ファイルからコンテキスト内でのチュートリアルを作成し、Google Cloud Console の右側のパネルに表示します。

実行中のチュートリアル

チュートリアルについて学ぶ（チュートリアルを使用して）

実際のインタラクティブなチュートリアルを操作してインタラクティブなチュートリアルについて学ぶには、下のボタンを使用して、チュートリアルの作成についてのチュートリアルを起動します。

チュートリアルを作成する

チュートリアルは Markdown で作成されます。具体的には HTML ではなく CommonMark 形式で、テキストエディタを使用して作成できます。チュートリアル固有の Markdown を使用してスポットライトやインラインアイコンを追加するなどの高度な機能を含むチュートリアルにディレクティブを追加して、わかりやすくすることもできます。

ステップを作成する

チュートリアルを作成するとき、見出しはその構造を決定するうえで重要です。適切なタイトル、ステップの見出し、および基本的な指示を設定するには、以下の階層に従います。

チュートリアルタイトルの H1（＃）タグ。チュートリアルの H1 タグは 1 つだけにする必要があります。
ステップのタイトルの H2（##）タグ。
サブステップのタイトルの H3（###）タグ。

チュートリアルの作成に使用できるサンプルの Markdown ファイルを次に示します。

# First Walkthrough

## First step

Hello World

### Part 1

Part One Instructions.

### Part 2

Part Two Instructions.

## Conclusion

Done!

コードブロックを追加する

コードスニペットをコールアウトするには、次のようにバックティックを使用します。

```
print("hello world")
```

コールアウトされたコードスニペットには、右端にクリップボードへのコピーボタンがあります。

ディレクティブを追加する

ディレクティブ（UI 要素のスポットライト、インラインアイコンの表示、ファイルアクションのトリガーなどの高度なチュートリアル機能）を追加するには、次のカスタム要素形式を使用します。

<walkthrough-directive-name param="optional parameter">
</walkthrough-directive-name>

この形式では、「directive-name」と「param」はプレースホルダです。たとえば、ディレクティブ editor-open-file とパラメータ filePath を使用する場合は、次の形式を使用します。

<walkthrough-editor-open-file filePath="test/hello.md">
</walkthrough-editor-open-file>

スポットライトを作成する

スポットライトは、ユーザーが Console 内の特定の UI 要素を見つけるのに役立つ視覚的な焦点です。

Console の要素にスポットライトを当てるには、次の形式を使用します。

<walkthrough-spotlight-pointer spotlightId="target" text="label text">
</walkthrough-spotlight-pointer>

Cloud Shell のウェブプレビューウィンドウを開くボタンにスポットライトを当てる場合は、次の形式を使用します。

<walkthrough-spotlight-pointer spotlightId="devshell-web-preview-button"
                               text="Open Cloud Shell">
</walkthrough-spotlight-pointer>

エディター内の要素については、editor-spotlight ディレクティブの使用を選択します。ユーザーが [My file] をクリックしたときに、既存の hello.md ファイルにスポットライトを当てるには、以下を使用します。

<walkthrough-editor-spotlight spotlightId="navigator" filePath="hello.md"
                              text="My file">
</walkthrough-editor-spotlight>

ヒント: スポットライト ID がない UI 要素の場合、CSS セレクタを使用できます。

インラインアイコンを使用する

Console ボタンの使用を効果的に呼び出すには、インラインアイコンを使用します。

たとえば、<walkthrough-cloud-shell-editor-icon></walkthrough-cloud-shell-editor-icon> は、Cloud Shell エディタアイコンのインラインアイコンを生成します。

ファイルアクションをトリガーする

また、チュートリアルに、ユーザーにとって役立つファイルを開くためのリンクを設定することもできます。ユーザーがチュートリアルを見て、表示テキスト「サンプルファイルを開く」をクリックするときに Cloud Editor でファイルを開くには、次のディレクティブを使用します。

<walkthrough-editor-open-file filePath="path/to/test.md"
                              text="Open sample file">
</walkthrough-editor-open-file>

このファイルはユーザーの Cloud Shell インスタンスに存在している必要があり、指定されるパスは相対ファイルパスである必要があります。このファイルは、ホームディレクトリまたはホームディレクトリのサブディレクトリのいずれかに配置する必要があります。

適切なディレクティブを見つける

チュートリアル Markdown リファレンスで、利用可能なすべての可能なスポットライト（およびそれらのパラメータ）の広範なリストを探します。

Cloud Shell でチュートリアルを起動する

Cloud Shell でチュートリアルをキックスタートするには、2 つの方法があります。

cloudshell launch-tutorial コマンドを使用する

Cloud Shell セッションで次の cloudshell コマンドを実行して、既存の Markdown ファイル tutorial.md からチュートリアルを起動します。
```
cloudshell launch-tutorial tutorial.md
```
または、Cloud Shell セッションで次のコマンドを実行して、teachme エイリアスを使用し、既存のファイル hello.md からチュートリアルを起動できます。
```
teachme hello.md
```
「Cloud Shell で開く」を使用する

または、「Cloud Shell で開く」機能を使用して、ユーザーをウェブサイト、ブログ、またはオープンソースプロジェクトから、git リポジトリでホストされているチュートリアルに誘導できます。「Cloud Shell で開く」機能は、「cloudshell_tutorial」パラメータを使用でき、URL の最後に &cloudshell_tutorial=path/to/file.md のように追加して、リポジトリ内のソース Markdown ファイルの場所を指定できます。つまり、チュートリアルにリンクされたボタンの Markdown は次のようになります。
```
[![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.png)](https://ssh.cloud.google.com/cloudshell/open?cloudshell_git_repo=https://github.com/testuser/myproject&cloudshell_tutorial=resources/hello.md)
```

次の手順

チュートリアル固有の Markdown 形式の全体的なリストについては、チュートリアル Markdown リファレンスをご覧ください。
効果的なチュートリアルを作成する方法のガイドラインについては、チュートリアル作成ガイドをご覧ください。