Referencias de Markdown para explicaciones

Los instructivos de Cloud Shell, también conocidos como “Explicaciones”, ayudan a los usuarios a familiarizarse de forma rápida y eficaz con tu proyecto, al mismo tiempo que facilitan su configuración y lanzamiento. Una explicación de Cloud Shell es un conjunto de instrucciones escritas en CommonMark de Markdown. Puede, además, incluir las directivas, que son expresiones de Markdown específicas para explicaciones, a fin de agregar funcionalidad avanzada, como destacar y seleccionar proyectos.

Consulte la Guía de explicaciones de escritura para saber cómo configurar, componer e iniciar una explicación en Cloud Shell.

Formato de la directiva

Para agregar una directiva, usa este formato:

<walkthrough-directive-name param-name="param-value">
</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>

Directivas de Cloud Shell

En las tablas siguientes, se enumeran las directivas y sus parámetros respectivos, que están disponibles para su uso durante la creación de una explicación en Cloud Shell.

Explicación de metadatos y diseño

Directiva: autor

<walkthrough-author></walkthrough-author>

Los metadatos sobre el autor se definen según la etiqueta del autor. Todos los parámetros son opcionales.

Parámetros Descripción
name Nombre del autor
repositoryUrl Vínculo hacia el repositorio que se utiliza para los comentarios
tutorialName ID de explicación

Directiva: duración de la explicación

<walkthrough-tutorial-duration></walkthrough-tutorial-duration>

La etiqueta de duración de la explicación muestra un ícono de reloj y un mensaje que calcula cuánto tiempo llevará la explicación.

Parámetros Descripción
duration Duración estimada de la explicación en minutos.

Directiva: tarjeta de explicación sugerida

<walkthrough-tutorial-card></walkthrough-tutorial-card>

Una etiqueta de tarjeta de explicación te vincula con una explicación sugerida.

Parámetros Descripción
url URL de la explicación.
icon Nombre del ícono
label Etiqueta las estadísticas de los eventos de clics

Directiva: nota al pie

<walkthrough-footnote>Footnote text here</walkthrough-footnote>

Una directiva de pie de página diseña el texto como un pie de página en la parte inferior del paso. El texto de la nota al pie se escribe como el texto interno.

Selección de proyectos

Directiva: configuración del proyecto

<walkthrough-project-setup></walkthrough-project-setup>

El usuario puede crear o seleccionar el proyecto que desea usar mediante el componente de configuración del proyecto. En este paso, el usuario no podrá continuar, a menos que seleccione un proyecto válido.

La etiqueta de permisos de proyecto establece los permisos de proyecto necesarios para la explicación. Si el usuario no posee los permisos del proyecto seleccionado, el proyecto no será considerado válido por la configuración.

Consulte la documentación para encontrar una descripción de cómo funcionan los permisos del proyecto.

Parámetros Descripción
permissions (Opcional) Lista de los permisos obligatorios, separada por comas

Directiva: proyecto y configuración de facturación

<walkthrough-project-billing-setup></walkthrough-project-billing-setup>

El usuario puede crear o seleccionar el proyecto que desea usar con el componente para la configuración del proyecto y la facturación. En este paso, no se permitirá que el usuario continúe, a menos que seleccione un proyecto válido con facturación habilitada.

Parámetros Descripción
permissions (Opcional) Lista de los permisos obligatorios, separada por comas

Elementos destacados y botones

Directiva: Puntero presentador

<walkthrough-spotlight-pointer>Label text here</walkthrough-spotlight-pointer>

La directiva del puntero presentador crea una etiqueta que destacará un elemento de IU específico en la pantalla. Solo se necesita uno de los parámetros. Si se proporcionan ambos, se utilizará spotlightId.

El puntero puede seleccionar un elemento por ID de instrumentación, que es una propiedad en el elemento DOM, o mediante un selector de CSS. Ambos tipos de selectores permiten que los selectores separados por comas coincidan con los elementos. Se destacarán todos los elementos que coincidan con el selector.

El texto de la etiqueta se escribe como el texto interno.

Parámetros Descripción
spotlightId El ID de instrumentación, puede usar comas para separar múltiples ID
cssSelector Un selector de CSS
Objetivos destacados/ID de instrumentación Descripción
console-nav-menu Menú de navegación de Console, hamburguesa en la parte superior izquierda
devshell-activate-button Botón para abrir Cloud Shell, cerca de la esquina superior derecha
devshell-web-editor-button Abre el editor Orion, en la barra superior de Cloud Shell
devshell-web-preview-button Abre una ventana de vista previa web de Cloud Shell

Para obtener información destacada dentro del marco del editor, consulte la sección de Directivas del editor.

Directiva: habilitar API

<walkthrough-enable-apis></walkthrough-enable-apis>

El componente habilitar API, crea un botón que habilita las API cuando se hace clic sobre él. Este paso permitirá que su proyecto tenga acceso a las API de GCP.

Consulte la documentación para saber qué API puede habilitar.

Parámetros Descripción
apis Lista separada por comas de las API que se pueden habilitar

Directiva: componente abierto de Cloud Shell

<walkthrough-open-cloud-shell-button></walkthrough-open-cloud-shell-button>

El componente abierto de Cloud Shell crea un botón que abre Cloud Shell cuando se hace clic (con el proyecto actual seleccionado).

Parámetros Descripción
open-cloud-shell Abre Cloud Shell cuando se visualiza el paso superior

Directiva: componente abierto de Cloud Shell en segundo plano

<walkthrough-devshell-precreate></walkthrough-devshell-precreate>

La directiva devshell-precreate aprovisiona una instancia de Cloud Shell en segundo plano para que la carga sea más rápida. Se ejecuta cuando se muestra el paso

Variables dinámicas

Directiva: vinculación de datos

<walkthrough-watcher-constant></walkthrough-watcher-constant>

Las explicaciones permiten la vinculación de datos en pares clave-valor. Los valores se configuran según las directivas, o los marcos de trabajo de la explicación. Se pueden definir dentro de la sesión de explicación utilizando la directiva watcher-constant.

Después, se puede hacer referencia al valor de strings con los siguientes elementos:

{{<key>}}

Ejemplo de uso en Markdown:

# My Walkthrough

## Step 1

<walkthrough-watcher-constant key="my-key" value="Hello Google">
</walkthrough-watcher-constant>

My message: {{my-key}}

Hay claves incorporadas disponibles:

Key Descripción del valor
project-id El ID del proyecto actual del usuario
project-name El nombre del proyecto del usuario

Directiva: Agente de observación constante

<walkthrough-watcher-constant></walkthrough-watcher-constant>

Un Observador es una cadena dinámica que se puede configurar para una explicación. Un agente de observación constante define el valor al comienzo de la explicación. Consulta la sección de enlace de datos para obtener más información.

Parámetros Descripción
key Clave para el agente de observación
value Valor del agente de observación

Directiva: iconos en línea

<walkthrough-inline-icon-name></walkthrough-inline-icon-name>

“inline-icon-name” es un marcador de posición para el icono que desea especificar (como nav-menu-icon y conclusion-trophy).

Los siguientes íconos están diseñados como íconos intercalados.

Nombre del icono en línea Icon
cloud-shell-icon Ícono de Cloud Shell
web-preview-icon Ícono de vista previa web
cloud-shell-editor-icon Ícono del editor de Cloud Shell
nav-menu-icon Ícono de menú de navegación
notification-menu-icon Ícono de menú de notificaciones
pin-section-icon Fijar el ícono de la sección del menú

Los siguientes íconos están diseñados como imágenes.

Nombre del icono en línea Icon
conclusion-trophy Trofeo de conclusión

Directivas del editor de Cloud Shell

Las directivas del editor son compatibles con la página del editor de Cloud Shell.

Directiva: archivo abierto

<walkthrough-editor-open-file></walkthrough-editor-open-file>

La directiva de archivo abierto crea una etiqueta en la que se puede hacer clic para abrir un archivo desde el disco de Cloud Shell en el editor.

El texto de la etiqueta se escribe como el texto interno.

Parámetros Descripción
filePath Ruta relativa del archivo

Directiva: abrir el texto seleccionado en el editor

<walkthrough-editor-select-line></walkthrough-editor-select-line>

La directiva editor-select-line crea una etiqueta en la que se puede hacer clic para abrir un archivo en el editor y seleccionar una línea de texto dentro de él.

Parámetros Descripción
filePath Ruta relativa del archivo
startLine Línea de inicio
startCharacterOffset Índice de inicio
endLine Línea de finalización
endCharacterOffset Índice de finalización

Directiva: Abrir el texto especificado regex en el editor

<walkthrough-editor-select-regex>Label text here</walkthrough-editor-select-regex>

La directiva editor-select-regex crea una etiqueta en la que se puede hacer clic para abrir un archivo en el editor y selecciona texto dentro de él, en función de la expresión regular proporcionada.

Parámetros Descripción
filePath Ruta relativa del archivo
regex Uso de Regex para buscar coincidencias

El texto de la etiqueta se escribe como el texto interno.

Directiva: Puntero presentador

<walkthrough-editor-spotlight>Label text here</walkthrough-editor-spotlight>

La directiva de Puntero presentador crea una etiqueta en la que se puede hacer clic que resaltará el elemento de IU especificado dentro del editor en la pantalla.

El puntero solo puede seleccionar objetivos predefinidos.

Parámetros Descripción
spotlightId ID del editor

El texto de la etiqueta se escribe como el texto interno.

Elementos que se pueden destacar con el editor Descripción
fileMenu Destaca el botón del menú de archivos
editMenu Destaca el botón del menú de edición
navigator Destaca un archivo específico del campo de elementos