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

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

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

実行中のチュートリアル

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

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

Cloud Shell で開く

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

チュートリアルは 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 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 つの方法があります。

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

    Cloud Shell セッションで次の cloudshell コマンドを実行して、既存の Markdown ファイル tutorial.md からチュートリアルを起動します。

    cloudshell launch-tutorial tutorial.md

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

    teachme hello.md

  2. 「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)

次の手順