Cloud Shell 中的教學課程

您可以在 Cloud Shell 中建立及啟用教學課程 (又稱逐步操作說明),協助使用者以快速有效的方式熟悉您的專案。

逐步操作說明是以 Markdown 編寫而成的一系列操作說明。Cloud Shell 會將文字內容剖析為不同的步驟和子步驟,透過這類 Markdown 檔案建立符合情境的教學課程,這些課程內容之後會顯示在 Google Cloud Console 的右側面板中。

實際應用逐步操作說明

瞭解教學課程

如要透過互動方式瞭解本頁所述功能,請點選下方的按鈕來開始教學課程,藉此瞭解如何編寫教學課程。

在 Cloud Shell 中開啟

編寫教學課程

逐步操作說明是以 Markdown 編寫而成 (以 CommonMark 格式為主,而且無須使用 HTML),因此可以透過任何文字編輯器撰寫。此外,您也可以在教學課程中使用課程專用的 Markdown,藉此新增包含進階功能的指令 (例如焦點和新增行內圖示),讓使用者更容易瞭解教學課程的內容。如要新增指令,請使用下列自訂元素格式:

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

建立步驟

在教學課程的製作過程中,標題會對課程的結構產生極大影響,因此使用時請務必謹慎。如想設定正確的課程標題、步驟標題和底層的操作說明,請按照以下階層進行設定:

  • H1 (#) 標記適用於教學課程的標題。教學課程中只能有一個 H1 標記。
  • H2 (##) 標記適用於步驟標題。
  • H3 (###) 標記適用於子步驟標題。

以下是您可以用來製作教學課程的範例 Markdown 檔案:

# First Tutorial

## First step

Hello World

### Part 1

Part One Instructions.

### Part 2

Part Two Instructions.

## Conclusion

Done!

新增程式碼區塊

如要標記特定程式碼片段,請按照下列方式使用倒引號:

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

系統顯示程式碼片段時,畫面右側角落會出現「複製到剪貼簿」按鈕。

建立焦點

焦點是一種醒目顯示方式,可協助使用者找到特定的 Cloud Console UI 元素。

如要強調某個 Cloud 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>

以下列出可套用焦點功能的目標物件:

Cloud Console 焦點目標 說明
devshell-activate-button 開啟 Cloud Shell 的按鈕,靠近畫面右上方。
devshell-web-editor-button 開啟 Orion 編輯器的按鈕,位於 Cloud Shell 的頂端列。
devshell-web-preview-button 在網頁中開啟 Cloud Shell 預覽視窗的按鈕。

如果您想要強調的是某個 Cloud Shell 編輯器元素,請使用下列指令碼格式:

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

您可以使用上述格式來執行下列指令。這樣一來,只要使用者點選 [我的檔案],已套用編輯器焦點功能的現有 hello.md 檔案就會以醒目的方式呈現:

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

可套用編輯器焦點功能的其他目標物件:

編輯器焦點目標 說明
fileMenu 醒目顯示檔案選單按鈕。
editMenu 醒目顯示編輯選單按鈕。
navigator 醒目顯示項目欄位中的特定檔案。

使用行內圖示

如果您想要以有效率的方式強調特定 Cloud Console 按鈕,可以使用行內圖示。

以下是您可以使用的圖示:

指令 說明
`walkthrough cloud-shell-icon` Cloud Shell 圖示
`walkthrough web-preview-icon` 網頁預覽圖示
`walkthrough cloud-shell-editor-icon` Cloud Shell 編輯器圖示

觸發檔案動作

另外,您也可以在教學課程中提供可開啟實用檔案的連結,讓使用者取得相關資源。如想讓使用者在進行教學課程時,只要點選顯示畫面文字 [開啟範例檔案],即可在 Cloud 編輯器中開啟特定檔案,請使用下列指令:

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

請注意,檔案必須位於使用者的 Cloud Shell 執行個體上,您提供的路徑也必須是該檔案的相關路徑。另外,檔案必須位於主目錄或主目錄中的任一子目錄中。

在 Cloud Shell 中啟用教學課程

您可以透過三種方式在 Cloud Shell 中啟用教學課程:

  1. 使用 teachme 指令

    Cloud Shell 工作階段中執行下列指令,透過現有的檔案「hello.md」啟動教學課程:

    teachme hello.md
    
  2. 使用「在 Cloud Shell 中開啟」功能

    或者,您也可以使用「在 Cloud Shell 中開啟」功能,將使用者從網站、網誌或開放原始碼專案帶往您製作的教學課程。您可以透過「在 Cloud Shell 中開啟」功能使用「教學課程」參數,並將這類參數新增至網址結尾 (例如 &tutorial=path/to/file.md)。在這種情況下,連結至教學課程的按鈕 Markdown 會如下所示:

    [![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.png)](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/testuser/myproject&tutorial=resources/hello.md)
    
  3. 使用 cloudshell launch-tutorial 指令

    Cloud Shell 工作階段中執行下列 cloudshell 指令,透過現有的 Markdown 檔案「tutorial.md」啟動教學課程:

    cloudshell launch-tutorial tutorial.md
    

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Cloud Shell