Walkthrough Markdown Reference

Cloud Shell tutorials, also known as Walkthroughs, help users familiarize themselves with your project quickly and effectively, while being easy to set up and launch. A Cloud Shell Walkthrough is a set of instructions written in CommonMark Markdown. It can also include directives which are Walkthrough specific Markdown expressions to add advanced functionality like spotlighting and project selection.

Refer to the Writing Walkthroughs guide for how to set up, compose, and launch a Walkthrough in Cloud Shell.

Directive format

To add a directive, use the following format:

<walkthrough-directive-name param-name="param-value">
</walkthrough-directive-name>

In this format, 'directive-name' and 'param' are placeholders. For example, if you'd like to use the directive, editor-open-file, and the parameter, filePath, use this format:

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

Cloud Shell directives

The tables below list the directives, and their respective parameters, available for use when authoring a Cloud Shell Walkthrough.

Walkthrough metadata and layout

Directive: Author

<walkthrough-author></walkthrough-author>

The author tag defines metadata about the author. All parameters are optional.

Parameters Description
name Author's name.
repositoryUrl Link to the repository which is used for feedback.
tutorialName Walkthrough id

Directive: Walkthrough Duration

<walkthrough-tutorial-duration></walkthrough-tutorial-duration>

The Walkthrough duration tag renders a clock icon and message estimating how long the Walkthrough will take.

Parameters Description
duration Estimated Walkthrough duration in minutes.

Directive: Suggested Walkthrough card

<walkthrough-tutorial-card></walkthrough-tutorial-card>

A Walkthrough card tag links to a suggested Walkthrough.

Parameters Description
url URL to the Walkthrough.
icon Icon name.
label Label for analytics for click events.

Directive: Footnote

<walkthrough-footnote>Footnote text here</walkthrough-footnote>

A footnote directive styles the text as a footnote at the bottom of the step. Footnote text is written as the inner text.

Project selection

Directive: Project setup

<walkthrough-project-setup></walkthrough-project-setup>

The project setup component helps the user create or select a project to use. This step will block the user from continuing until a valid project has been selected.

The project permissions tag sets required project permissions for the Walkthrough. If the user lacks the permissions on the selected project, the project setup will not consider it a valid project.

See the documentation for a description of how project permissions work.

Parameters Description
permissions (Optional) Comma separated list of required permissions.

Directive: Project and billing setup

<walkthrough-project-billing-setup></walkthrough-project-billing-setup>

The project and billing setup component helps the user create or select a project to use. This step will block the user from continuing until a valid project with billing enabled has been selected.

Parameters Description
permissions (Optional) Comma separated list of required permissions.

Spotlights and buttons

Directive: Spotlight pointer

<walkthrough-spotlight-pointer>Label text here</walkthrough-spotlight-pointer>

The spotlight pointer directive creates a clickable label that will spotlight the specified UI element on the screen. Only one of the parameters is needed. If both are provided, the spotlightId will be used.

The pointer can select an element by instrumentation id, which is a property on the DOM element, or by using a CSS selector. Both types of selectors allow comma separated selectors to match elements. All elements matching the selector will be highlighted.

Label text is written as the inner text.

Parameters Description
spotlightId Instrumentation ID, can use commas to separate multiple IDs.
cssSelector A CSS selector
Spotlight targets/instrumentation IDs Description
console-nav-menu Console navigation menu, hamburger in top left.
devshell-activate-button Button to open Cloud Shell, near top right.
devshell-web-editor-button Opens Orion editor, on Cloud Shell's top bar.
devshell-web-preview-button Opens a web preview window for Cloud Shell.

For spotlights within the editor frame, see the section of Editor directives.

Directive: Enable APIs

<walkthrough-enable-apis></walkthrough-enable-apis>

The enable APIs component creates a button that enables APIs when clicked. This will allow your project to access the GCP APIs.

Refer to the documentation for which APIs you can enable.

Parameters Description
apis Comma separated list of APIs to enable.

Directive: Open Cloud Shell

<walkthrough-open-cloud-shell-button></walkthrough-open-cloud-shell-button>

The open Cloud Shell component creates a button that opens Cloud Shell when clicked (with the current project selected).

Parameters Description
open-cloud-shell Opens Cloud Shell when the parent step is viewed.

Directive: Open Cloud Shell in the background

<walkthrough-devshell-precreate></walkthrough-devshell-precreate>

The devshell-precreate directive provisions a Cloud Shell instance in the background so the load is faster. Runs when the step is shown.

Dynamic variables

Directive: Data binding

<walkthrough-watcher-constant></walkthrough-watcher-constant>

Walkthroughs allow data binding for key-value pairs. The values are set by directives or by the Walkthrough framework. They can be defined within the Walkthrough session using the directive watcher-constant.

Afterwards, the string value can be referenced with:

{{<key>}}

Example usage in Markdown:

# My Walkthrough

## Step 1

<walkthrough-watcher-constant key="my-key" value="Hello Google">
</walkthrough-watcher-constant>

My message: {{my-key}}

There are built-in keys available:

Key Value description
project-id The user's current project id.
project-name The user's project name.

Directive: Watcher constant

<walkthrough-watcher-constant></walkthrough-watcher-constant>

A Watcher is a dynamic string that can be set for a Walkthrough. A watcher constant defines the value at the beginning of the Walkthrough. See the data binding section for more information.

Parameters Description
key Key to the watcher.
value Value of the watcher.

Directive: Inline icons

<walkthrough-inline-icon-name></walkthrough-inline-icon-name>

'inline-icon-name' is a placeholder for the icon you'd like to specify (like nav-menu-icon and conclusion-trophy).

The following icons are styled as inline icons.

Inline icon name Icon
cloud-shell-icon Cloud Shell Icon
web-preview-icon Web Preview Icon
cloud-shell-editor-icon Cloud Shell Editor Icon
nav-menu-icon Nav Menu Icon
notification-menu-icon Notification Menu Icon
pin-section-icon Pin Menu Section Icon

The following icons are styled as images.

Inline icon name Icon
conclusion-trophy Conclusion Trophy

Cloud Shell Editor directives

Editor directives are supported by the Cloud Shell Editor page.

Directive: Open file

<walkthrough-editor-open-file></walkthrough-editor-open-file>

The open file directive creates a clickable label to open a file from the Cloud Shell disk in the editor.

Label text is written as the inner text.

Parameters Description
filePath Relative file path

Directive: Open selected text in editor

<walkthrough-editor-select-line></walkthrough-editor-select-line>

The editor-select-line directive creates a clickable label to open a file in the editor and select a line of text within it.

Parameters Description
filePath Relative file path
startLine Start line
startCharacterOffset Start index
endLine End line
endCharacterOffset End index

Directive: Open regex specified text in editor

<walkthrough-editor-select-regex>Label text here</walkthrough-editor-select-regex>

The editor-select-regex directive creates a clickable label to open a file in the editor and selects text within it, based on the provided regex.

Parameters Description
filePath Relative file path
regex Regex to match

Label text is written as the inner text.

Directive: Spotlight pointer

<walkthrough-editor-spotlight>Label text here</walkthrough-editor-spotlight>

The spotlight pointer directive creates a clickable label that will spotlight the specified UI element within the editor on the screen.

The pointer can only select predefined targets.

Parameters Description
spotlightId Editor ID

Label text is written as the inner text.

Editor spotlight targets Description
fileMenu Highlights the file menu button.
editMenu Highlights the edit menu button.
navigator Highlight a file specified in the item field.
Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Shell