Schritt-für-Schritt-Anleitungen in Cloud Shell erstellen

Cloud Shell unterstützt das Erstellen und Starten von Anleitungen, Walkthroughs genannt, damit sich Nutzer schnell und effektiv mit Ihrem Projekt vertraut machen können.

Ein Walkthrough ist eine Reihe von Anweisungen, die in Markdown geschrieben werden. Cloud Shell erstellt aus diesen Markdown-Dateien Schritt-für-Schritt-Anleitung im Kontext, indem der Text in Schritte und Unterschritte unterteilt wird, die dann im rechten Bereich der Google Cloud Console angezeigt werden.

Walkthrough in Aktion

Erfahren Sie mehr über Schritt-für-Schritt-Anleitungen (mithilfe einer Schritt-für-Schritt-Anleitung!)

Wenn Sie mehr über interaktive Schritt-für-Schritt-Anleitungen erfahren möchten, indem Sie eine tatsächliche interaktive Schritt-für-Schritt-Anleitung erstellen, starten Sie die Schritt-für-Schritt-Anleitung zum Schreiben von Schritt-für-Schritt-Anleitungen mithilfe der folgenden Schaltfläche:

In Cloud Shell öffnen

Eine Schritt-für-Schritt-Anleitung schreiben

Walkthroughs werden in Markdown geschrieben, genauer gesagt im CommonMark-Format und ohne HTML. Sie können mit jedem Texteditor entwickelt werden. Sie können Ihrer Schritt-für-Schritt-Anleitung auch Anweisungen hinzufügen, die erweiterte Funktionen wie das Hervorheben und Hinzufügen von Inline-Symbolen mit Schritt-für-Schritt-Anleitungs-spezifischem Markdown enthalten, um das Befolgen zu vereinfachen.

Schritte erstellen

Beim Erstellen einer Schritt-für-Schritt-Anleitung sind Überschriften zum Festlegen der Struktur wichtig. Folgen Sie der nachstehenden Hierarchie, um den richtigen Titel sowie die Schrittüberschriften und zugrunde liegende Anweisungen festzulegen:

  • H1 (#)-Tags für den Titel der Schritt-für-Schritt-Anleitung. Die Schritt-für-Schritt-Anleitung sollte nur einen einzigen H1-Tag aufweisen.
  • H2 (##)-Tags für eine Schrittüberschrift
  • H3 (###)-Tags für die Überschrift eines Unterschritts

Hier ist eine Markdown-Beispieldatei, mit der Sie eine Schritt-für-Schritt-Anleitung erstellen können:

# First Walkthrough

## First step

Hello World

### Part 1

Part One Instructions.

### Part 2

Part Two Instructions.

## Conclusion

Done!

Codeblocks hinzufügen

Um auf ein Code-Snippet zu verweisen, verwenden Sie Graviszeichen wie folgt:

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

Das resultierende Code-Snippet enthält in der rechten Ecke eine Schaltfläche zum Kopieren in die Zwischenablage.

Anweisungen hinzufügen

Verwenden Sie das folgende benutzerdefinierte Elementformat, um eine Anweisung hinzuzufügen (erweiterte Funktionen für Schritt-für-Schritt-Anleitungen wie das Hervorheben eines UI-Elements, das Anzeigen eines Inline-Symbols und das Auslösen von Dateiaktionen):

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

In diesem Format sind "directive-name" und "param" Platzhalter. Wenn Sie beispielsweise die Anweisung editor-open-file und den Parameter filePath verwenden möchten, nutzen Sie dieses Format:

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

Spotlight erstellen

Ein Spotlight ist eine optische Hervorhebung, durch die Nutzer ein bestimmtes Oberflächenelement der Console leichter finden können.

Verwenden Sie das folgende Format, um ein Console-Element mit einem Spotlight hervorzuheben:

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

Praktisches Beispiel: Wenn Sie etwa die Schaltfläche zum Öffnen des Web-Vorschaufensters für Cloud Shell hervorheben möchten, verwenden Sie Folgendes:

<walkthrough-spotlight-pointer spotlightId="devshell-web-preview-button"
                               text="Open Cloud Shell">
</walkthrough-spotlight-pointer>

Verwenden Sie für Elemente im Editor die Anweisung editor-spotlight. Verwenden Sie Folgendes, um eine vorhandene hello.md-Datei hervorzuheben, wenn ein Nutzer auf "Meine Datei" klickt:

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

Tipp: Für UI-Elemente ohne Spotlight-IDs können Sie einen CSS-Selektor verwenden.

Inline-Symbole verwenden

Verwenden Sie ein Inline-Symbol, um effektiv auf die Verwendung einer Console-Schaltfläche hinzuweisen.

Beispielsweise erzeugt <walkthrough-cloud-shell-editor-icon></walkthrough-cloud-shell-editor-icon> ein Inline-Symbol des Cloud Shell-Editor-Symbols Cloud Shell-Symbol.

Dateiaktionen auslösen

Darüber hinaus können Sie Links in Ihrer Schritt-für-Schritt-Anleitung verwenden, die hilfreiche Dateien für Nutzer öffnen. Verwenden Sie die folgende Anweisung, um eine Datei im Cloud Editor zu öffnen, wenn ein Nutzer Ihre Schritt-für-Schritt-Anleitung schrittweise durcharbeitet und auf den Anzeigetext "Beispieldatei öffnen" klickt:

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

Beachten Sie, dass die Datei in der Cloud Shell-Instanz des Nutzers vorhanden sein muss und dass der angegebene Pfad der relative Dateipfad sein muss. Die Datei muss sich im Home-Verzeichnis oder in einem der Unterverzeichnisse des Home-Verzeichnisses befinden.

Die richtigen Anweisungen finden

In der Schritt-für-Schritt-Anleitung zur Markdown-Referenz finden Sie eine ausführliche Liste aller möglichen Spotlights (und ihrer Parameter), die Ihnen zur Verfügung stehen.

Schritt-für-Schritt-Anleitungen in Cloud Shell starten

Es gibt zwei Möglichkeiten, eine Schritt-für-Schritt-Anleitung in Cloud Shell zu starten:

  1. Den Befehl cloudshell launch-tutorial ausführen

    Führen Sie den folgenden cloudshell-Befehl in Ihrer Cloud Shell-Sitzung aus, um eine Schritt-für-Schritt-Anleitung aus einer vorhandenen Markdown-Datei tutorial.md zu starten:

    cloudshell launch-tutorial tutorial.md
    

    Alternativ können Sie den Alias teachme verwenden, indem Sie den folgenden Befehl in Ihrer Cloud Shell-Sitzung ausführen, um eine Schritt-für-Schritt-Anleitung aus einer vorhandenen Datei hello.md zu starten:

    teachme hello.md
    
  2. "In Cloud-Shell öffnen" verwenden

    Alternativ können Sie die Funktion "In Cloud Shell öffnen" verwenden, um Ihre Nutzer von einer Website, einem Blog oder einem Open Source-Projekt zu Ihrer Schritt-für-Schritt-Anleitung zu führen, der in einem Git-Repository gehostet wird. Die Funktion "In Cloud Shell öffnen" ermöglicht einen Parameter "cloudshell_tutorial" und kann als &cloudshell_tutorial=path/to/file.md am Ende der URL hinzugefügt werden, um den Speicherort der Quell-Markdown-Datei im Repository anzugeben. Der Markdown-Code für eine mit Ihrer Schritt-für-Schritt-Anleitung verknüpfte Schaltfläche sieht demnach so aus:

    [![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)
    

Nächste Schritte