Escribir tutoriales en Cloud Shell

Cloud Shell permite crear y lanzar tutoriales para ayudar a los usuarios a familiarizarse con tu proyecto de forma rápida y eficaz.

Un tutorial es un conjunto de instrucciones escritas en Markdown. Cloud Shell crea tutoriales contextuales a partir de estos archivos Markdown analizando el texto en pasos y subpasos que se muestran en un panel de la consola de Google Cloud .

Un tutorial que se ejecuta en Cloud Shell

Escribir tutoriales

Los tutoriales se escriben en Markdown de CommonMark. También se admiten extensiones de Markdown adicionales y directivas, que incluyen funciones avanzadas, como destacar funciones y añadir iconos insertados.

Pasos

Al crear un tutorial, los encabezados son importantes para determinar su estructura. Para definir el título, los encabezados de los pasos y las instrucciones correspondientes, usa la siguiente jerarquía:

  • Etiquetas H1 (#) para el título del tutorial. Solo debe haber una etiqueta H1 en un tutorial.
  • Etiquetas H2 (##) para el título de un paso.
  • Etiquetas H3 (###) para el título de un subpaso.

Aquí tienes un archivo de Markdown de ejemplo que puedes usar para crear un tutorial:

# First tutorial

## First step

Hello world

### Part 1

Part one instructions.

### Part 2

Part two instructions.

## Conclusion

Done!

Directivas

Las directivas permiten usar funciones avanzadas, como destacar funciones y añadir iconos insertados.

Para añadir una directiva, utiliza el siguiente formato:

<walkthrough-DIRECTIVE_NAME PARAMETER="PARAMETER_VALUE">
</walkthrough-DIRECTIVE_NAME>

Por ejemplo, si quieres usar la directiva editor-open-file y el parámetro filePath, se escribiría de la siguiente manera:

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

Para ver las directivas disponibles, consulta la referencia de directivas.

Lanzar tutoriales en Cloud Shell

Hay dos formas de iniciar un tutorial en Cloud Shell:

  1. Usar el comando cloudshell launch-tutorial

    Ejecuta el siguiente comando cloudshell en tu sesión de Cloud Shell para iniciar un tutorial a partir de un archivo Markdown, tutorial.md:

    cloudshell launch-tutorial tutorial.md

    También puedes usar el alias teachme ejecutando el siguiente comando en tu sesión de Cloud Shell para iniciar un tutorial desde un archivo, hello.md:

    teachme hello.md

  2. Usar Abrir en Cloud Shell

    También puedes usar la función Abrir en Cloud Shell para guiar a los usuarios desde un sitio web, un blog o un proyecto de código abierto hasta el tutorial alojado en un repositorio de Git. La función Abrir en Cloud Shell permite usar un parámetro cloudshell_tutorial, que se puede añadir al final de la URL para especificar la ubicación del archivo Markdown de origen en el repositorio. Esto significa que el código Markdown de un botón vinculado a tu tutorial sería el siguiente:

    [![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.png)](https://ssh.cloud.google.com/cloudshell/open?cloudshell_git_repo=GIT_REPO_URL&cloudshell_tutorial=PATH_TO_MD_FILE)

Pasos siguientes