Redacta explicaciones 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 explicaciones en contexto a partir de estos archivos de Markdown analizando el texto en pasos y subpasos que luego se muestran en el panel de la derecha en Google Cloud Console.

Explicación en acción

Aprender sobre explicaciones (¡utilizando una explicación!)

Para obtener información sobre explicaciones interactivas trabajando a través de una explicación interactiva real, inicie la explicación sobre cómo escribir explicaciones usando el botón a continuación:

Abrir en Cloud Shell

Escribir una explicación

Las explicaciones se escriben con Markdown, específicamente en formato CommonMark y sin HTML, y se pueden desarrollar con cualquier editor de texto. También puede agregar directivas a su explicación que incluyen funcionalidad avanzada, como destacar y agregar iconos en línea, con Markdown específico de la explicación para que sea más fácil de seguir.

Crea pasos

Al crear una explicación, los encabezados son importantes para determinar su estructura. 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:

  • Etiquetas H1 (#) para el título de la explicación. Solo debe haber una sola etiqueta H1 en la explicación.
  • H2 (##) etiquetas para un título secundario.
  • H3 (###) etiquetas para un título terciario.

Aquí hay un archivo de Markdown de muestra que puede usar para crear una explicación:

# First Walkthrough

## 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 avanzada de recorrido como destacar un elemento de la interfaz de usuario, mostrar un icono en línea y activar acciones de archivo), use 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

Además, puede tener enlaces en su explicación que abren archivos útiles para los usuarios. Para abrir un archivo en Cloud Editor mientras su usuario recorre su explicación y hace clic en el texto de la pantalla, “Open sample file”, use 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.

Lanzamiento de explicaciones en Cloud Shell

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

  1. Usa el comando cloudshell launch-tutorial

    Ejecute el siguiente comando cloudshell en su sesión de Cloud Shell para iniciar una explicación 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 una explicación desde un archivo existente, hello.md:

    teachme hello.md
    
  2. Usa “Abrir en Cloud Shell”

    Alternativamente, puede usar la función “Abrir en Cloud Shell” para guiar a sus usuarios desde un sitio web, blog o proyecto de código abierto, a su explicación alojada en un repositorio 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 el Markdown para un botón vinculado a su explicación se vería así:

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