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 el panel del lado derecho de Google Cloud Console.

Instructivo en acción

Aprenderás sobre instructivos (usa un instructivo)

Si quieres aprender sobre instructivos interactivos a través de un instructivo interactivo real, inicia el instructivo sobre cómo escribir instructivos con el botón que se encuentra a continuación:

Abrir en Cloud Shell

Cómo escribir un instructivo

Los instructivos se escriben con Markdown, específicamente en formato CommonMark y sin HTML, y se pueden desarrollar con cualquier editor de texto. También puedes agregar directivas a tu instructivo que incluyen funciones avanzadas, como destacar y agregar íconos intercalados con la Markdown específica para instructivos a fin de que sea más fácil de seguir.

Crea pasos

Los encabezados son importantes para determinar la estructura del instructivo que vas a crear. A fin de asignar el título correcto, los pasos de los encabezados y las instrucciones subyacentes, sigue la jerarquía que se indica a continuación:

  • H1 (#) etiquetas para el título del instructivo. Debe haber solo una etiqueta H1 en el 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!

Agrega un bloque de código

Usa acentos graves de la siguiente manera, para destacar un fragmento de código:

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

El fragmento de código obtenido incluye un botón para “Copiar al portapapeles” en la esquina del lado derecho.

Agregar directivas

Para agregar una directiva (funcionalidad de instructivo avanzada, como destacar un elemento de la IU, mostrar un ícono intercalado y activar acciones de archivos), usa el siguiente formato de elemento personalizado:

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

En este formato, “directive-name” y “param” son marcadores de posición. Por ejemplo, si desea utilizar la directiva, editor-open-file, y el parámetro, filePath, use este formato:

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

Crea un punto destacado

Un punto destacado es un enfoque visual para ayudar a los usuarios a encontrar un elemento de interfaz de usuario específico dentro de la consola.

Para destacar un elemento de la consola, use este formato:

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

En la práctica, si deseas destacar el botón que abre la ventana de vista previa web en Cloud Shell, usa lo siguiente:

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

Para los elementos dentro del editor, elija usar la directiva editor-spotlight. Para destacar un archivo hello.md existente cuando un usuario hace clic en “My file”, use:

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

Consejo: Para los elementos de la interfaz de usuario que no tienen ID de punto destacado, puede usar un selector CSS.

Usa un ícono intercalado

Para destacar de forma eficaz el uso de un botón de Console, usa un ícono intercalado.

Por ejemplo, <walkthrough-cloud-shell-editor-icon></walkthrough-cloud-shell-editor-icon> produce un icono en línea del icono del editor de Cloud Shell Ícono de Cloud Shell.

Activa acciones en los archivos

Puedes, además, tener vínculos en tu instructivo que abran los archivos que sean útiles para los usuarios. Para abrir un archivo en Cloud Editor a medida que tu usuario recorre tu instructivo y hace clic en el texto en pantalla que indica: “Abrir archivo de muestra”, usa la siguiente directiva:

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

Nota, el archivo debe existir en la instancia de Cloud Shell del usuario y la ruta proporcionada debe ser su ruta de archivos relativa. El archivo debe estar ubicado en el directorio de página principal o en cualquiera de los subdirectorios del directorios de página principal.

Encuentra las directivas correctas

Busque la Referencia de Markdown de la explicación para obtener una lista extensa de todos los puntos destacados posibles (y sus parámetros) disponibles para usted.

Lanzar instructivos en Cloud Shell

Existen dos maneras de iniciar un instructivo 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
    

    Como alternativa, puedes usar el alias teachme si ejecutas el siguiente comando en tu 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 característica “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 Git. . La función “Abrir en Cloud Shell” permite un parámetro “cloudshell_tutorial”, y se puede agregar al final de la URL como tal &cloudshell_tutorial=path/to/file.md 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=https://github.com/testuser/myproject&cloudshell_tutorial=resources/hello.md)
    

Próximos pasos