Cómo escribir instructivos en Cloud Shell

Cloud Shell admite la compilación y el lanzamiento de instructivos llamados explicaciones, que ayudan a que los usuarios se familiaricen de forma rápida y eficaz con tu proyecto.

Una explicación es un conjunto de instrucciones escritas con Markdown. Cloud Shell crea instructivos en contexto a partir de estos archivos de Markdown, mediante el análisis del texto en pasos principales y secundarios que, posteriormente, se muestran en un panel de la consola de Google Cloud.

Un instructivo que se ejecuta en Cloud Shell

Escribe instructivos

Los instructivos se escriben en Markdown de CommonMark. Se admiten extensiones de Markdown adicionales, al igual que directivas, que incluyen funciones avanzadas, como funciones de destaque y la adición de íconos intercalados.

Pasos

Los encabezados son importantes para determinar la estructura del instructivo que vas a crear. Para establecer el título correcto, los pasos de los encabezados y las instrucciones subyacentes, usa la siguiente jerarquía:

  • H1 (#) etiquetas para el título del instructivo. Solo debe haber una etiqueta H1 en un instructivo.
  • H2 (##) etiquetas para un título secundario.
  • H3 (###) etiquetas para un título terciario.

Este es un archivo de muestra de Markdown que puedes usar para crear un instructivo:

# First tutorial

## First step

Hello world

### Part 1

Part one instructions.

### Part 2

Part two instructions.

## Conclusion

Done!

Directivas

Las directivas habilitan funciones avanzadas, como destacar funciones y agregar íconos intercalados.

Para agregar una directiva, usa este formato:

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

Por ejemplo, si deseas 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 conocer las directivas disponibles, consulta la referencia de directivas.

Cómo iniciar instructivos en Cloud Shell

Hay dos formas de iniciar una explicación en Cloud Shell:

  1. Usa el comando cloudshell launch-tutorial

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

    cloudshell launch-tutorial tutorial.md

    Alternativamente, puede usar el alias teachme ejecutando el siguiente comando en su sesión de Cloud Shell para iniciar un instructivo desde un archivo existente, hello.md:

    teachme hello.md

  2. Usa Abrir en Cloud Shell

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

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

Próximos pasos