在 Cloud Shell 中编写演示

Cloud Shell 支持构建和启动教程(也称作“演示”),这些教程可帮助用户快速而有效地熟悉您的项目。

演示是一套用 Markdown 编写的说明。Cloud Shell 可以将 Markdown 文件中的文本解析为步骤和子步骤(这些步骤和子步骤随后会显示在 Google Cloud Console 的右侧面板中),从而创建出上下文演示。

演示的实际应用

了解演示(使用演示!)

要通过实际应用来了解交互式演示,请使用以下按钮启动关于编写演示的演示:

在 Cloud Shell 中打开

编写演示

您需要以 Markdown 格式来编写演示(具体来讲,是指以 CommonMark 格式编写,而不使用 HTML)。制作演示时,可以使用任何文本编辑器。您还可以使用演示专用的 Markdown 在演示中添加指令(包括聚焦和添加内嵌图标等高级功能),从而使其更易于遵循。

创建步骤

在创建演示时,标题对于确定其结构非常关键。要设置正确的标题、步骤标题和底层指令,请遵循以下层次结构:

  • H1 (#) 标记是演示标题。一个演示中只能包含一个 H1 标记。
  • H2 (##) 标记是步骤标题。
  • H3 (###) 标记是子步骤标题。

以下是一个示例 Markdown 文件,您可利用它来创建一个演示:

# First Walkthrough

## First step

Hello World

### Part 1

Part One Instructions.

### Part 2

Part Two Instructions.

## Conclusion

Done!

添加一个代码块

要调出一段代码,请按如下所示使用反引号:

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

最终生成的代码片段会显示在右侧一角,并带有一个复制到剪贴板的按钮。

添加指令

要添加指令(高级演示功能,例如,聚焦界面元素、显示内嵌图标以及触发文件操作),请使用以下自定义元素格式:

<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>

创建一个聚焦

聚焦是一种视觉焦点功能,可帮助用户找到控制台内的特定界面元素。

要聚焦控制台元素,请使用以下格式:

<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 指令。要在用户点击“我的文件”时聚焦现有的 hello.md 文件,请使用:

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

提示:对于没有 Spotlight ID 的界面元素,您可以使用 CSS 选择器

使用内嵌图标

要有效调出使用控制台按钮,请使用内嵌图标。

例如,<walkthrough-cloud-shell-editor-icon></walkthrough-cloud-shell-editor-icon> 生成 Cloud Shell 编辑器图标 Cloud Shell 图标 的内嵌图标。

触发文件操作

此外,您还可以在演示中加入可打开有用文件的链接。要在用户浏览演示并点击显示文本“Open sample file”(打开示例文件)时在 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 中启动演示:

  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”参数,并且可以通过在网址的末尾添加,因此,可以使用 &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)
    

后续步骤