Walkthrough Markdown Reference

Cloud Shell tutorials, also known as Walkthroughs, help users familiarize themselves with your project quickly and effectively, while being easy to setup 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>

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

Author

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

author Creates metadata for the Walkthrough author.
name Author's name.
repositoryUrl Link to the repository which is used for feedback.
tutorialName Walkthrough id

Walkthrough duration

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

tutorial-duration Displays a Walkthrough duration.
duration Estimated Walkthrough duration in minutes.

Walkthrough card

A Walkthrough card tag links to a suggested Walkthrough.

tutorial-card Display a suggested Walkthrough.
url URL to the Walkthrough.
icon Icon name.
label Label for analytics for click events.

Footnote

A footnote directive styles the text as a footnote at the bottom of the step.

Footnote text is written as the inner text.

footnote Displays text as a footnote.

Project selection

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.

project-setup Substitutes the project setup step.
permissions (Optional) Comma separated list of required permissions.

Project and 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.

project-billing-setup Substitutes the project setup step with billing required.
permissions (Optional) Comma separated list of required permissions.

Spotlights and buttons

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.

spotlight-pointer Substitutes a spotlight pointer.
spotlightId Instrumentation ID, can use commas to separate multiple IDs.
cssSelector A CSS selector
GCP Console spotlight targets 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.

Enable APIs

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

See the documentation for which APIs you can enable.

enable-apis Displays a component to enable APIs.
apis Comma separated list of APIs to enable.

Open Cloud Shell

The open Cloud Shell component creates a button that opens Cloud Shell when clicked.

open-cloud-shell-button Displays a component to open Cloud Shell with the current project selected.
open-cloud-shell Opens Cloud Shell when the parent step is viewed.
devshell-precreate Provisions a Cloud Shell instance in background so the load is faster. Runs when the step is shown.

Dynamic variables

Data binding

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:

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

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.

watcher-constant Defines a string value at render time.
key Key to the watcher.
value Value of the watcher.

Icon directives

The following icons are styled as inline icons.

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

Directive Icon
conclusion-trophy Conclusion Trophy

Cloud Shell Editor directives

Editor directives are supported by the Cloud Shell Editor page.

Open file

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

Label text is written as the inner text.

editor-open-file Opens a file from Cloud Shell in the Editor.
filePath Relative file path

Select text

The select text directive creates a clickable label to open a file and select text within it.

editor-select-line Selects specified text in the editor.
filePath Relative file path
startLine Start line
startCharacterOffset Start index
endLine End line
endCharacterOffset End index
editor-select-regex Selects specified text in the editor.
filePath Relative file path
regex Regex to match

Label text is written as the inner text.

Spotlight pointer

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

The pointer can only select predefined targets.

editor-spotlight Spotlights a predefined target.
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.
Kunde den här sidan hjälpa dig? Berätta:

Skicka feedback om ...