• Qué es un Codelab
• Formato markdown para Codelabs
• Metadata
• Contenido del markdown
• Estimación de tiempo por diapositiva
• Fragmentos de código
• Reglas para publicar un Codelab
• Lista de categorías
• Ejemplo de un Codelab
• Referencias

Un Codelab es un conjunto de diapositivas que sirven como tutorial interactivo, se puede crear utilizando Google Docs o un archivo markdown. Para ver algunos ejemplos de Codelabs, se puede visitar el sitio de Google Codelabs.

Características

• Es atractivo, mantiene la atención del usuario.
• Interfaz de usuario sencilla, es fácil de usar.
• Interfaz responsiva, se ajusta tanto a una implementación web como a una implementación móvil.
• Y todo ésto, se puede crear sin escribir una sola línea de código.

Principalmente, un archivo md para Codelabs se compone de 2 partes:

1. Metadata: son datos que usa el motor de Codelab para publicar correctamente el Codelab. .
2. Conetenido: es tal cual el contenido del Codelab, éste es escrito utilizando markdown. Si se requiere, se puede leer esta guía básica de sintaxis markdown.

La metadata es lo primero que se debe agregar en el archivo markdown con el formato key: value. La metadata requerida para la publicación del Codelab es:

• summary: Una descripción corta del Codelab
• id: El nombre del folder que se generará al publicar el Codelab, sólo debe contener caracteres alfanuméricos, sin acentuaciones y separado por guiones medios.
• categories: La categoría en la que se agrupará al Codelab, la herramienta para generar los Codelabs, contiene unas categorías por default, las cuáles además de agrupar el Codelab, también muestran una imagen en la tarjeta de vista previa.
• environments: Establece el ambiente en el que se publicará el Codelab, actualmente sólo se utilizará environments: Web
• status: Pueden ser Draft, Published, Deprecated o Hidden. Se puede seleccionar uno o más de estos estados, pero siempre y cuando el Codelab no se autorice para su publicación, se debe utilizar status: Draft.
• feedback link: El URL a donde se redigirá al usuario al dar click en el botón para reportar un bug en el Codelab (Opcional).
• analytics account: Le permite especificar un ID de Google Analytics para el Codelab (Opcional).
• tags: Etiquetas relevantes para hacer más fácil la búsqueda del Codelab.
• authors: Nombre del o los autores del Codelab.

summary: How to Write a Codelab
id: how-to-write-a-codelab
categories: howto
tags: howto, Codelabs, tutorial
status: Draft
authors: Erik Valdivieso, Miguel Osbaldo

Como ya se mencionó antes, se requiere de un documento markdown para crear un Codelab. Este documento tiene una sintaxis normal de markdown, a excepción de los headers que ya se explicaron anteriormente y de la estimación de tiempo por paso.

El header # será el título/nombre d,

También se debe seguir unos formatos específicos para la inserción de fragmentos de código, más adelante se especificará éstos.

Para indicar un estimado de cuánto tiempo tomará avanzar por las diapositivas, se utiliza el metadata Duration insertándolo debajo de cada encabezado de nivel 2 (es decir ##).

A esta metadata se le asigna un valor entero, el cual indica los minutos que se estima se tardará en completar la diapositiva, p.e Duration: 4 indica que se estima que esa diapositiva se completará en 4 minutos.

El tiempo total se calculará automáticamente y se mostrará en el Codelab una vez se haya creado.

El motor de Codelabs interpreta estos fragmentos de código y les da un formato dependiendo de cómo se inserten. Para incluir fragmentos de código, se debe hacer de dos formas:

• Puede resaltar en línea, puede encerrar los caracteres usando el acento o comilla invertidos: "`x = 2`".
• Para insertar bloques de código se usan tres acentos invertidos como delimitadores al inicio y al final del bloque. Seguido de los tres primeros acentos invertidos, se debe escribir el nombre del lenguaje del código, por ejemplo:

JavaScript

Si se inserta un bloque de código Javascript, se tendría que escribir de la siguiente manera:

```javascript
{
  key1: "string",
  key2: integer,
  key3: "string"
}
```

Esto se vería de la siguiente forma:

  {
    key1: "string",
    key2: integer,
    key3: "string"
  }

Java

Si el código es en lenguaje Java

```java
for (int i = 1; i < length i++;) {
  // bloque de código
}
```

El resultado sería:

for (int i = 1; i < length i++;) {
  // bloque de código
}

Para publicar un Codelab en CONACyT se debe cumplir con ciertas reglas:

• Los Codelabs de CONACyT deben ser en archivos Markdown (no es posible usar archivos de Google Docs)
• La redacción debe ser en tercera persona y debe ser consistente
• La ID del Codelab debe coincidir con el nombre del archivo Markdown y su directorio dentro de assets.
• Los archivos, y por consiguiente los IDs, deben ser nombrados sólo con caracteres alfanuméricos, sin acentuaciones y separado por guiones medios, p.e. ejemplo-de-nombre-1.md.
• Si el documento Markdown tiene imágenes, debe ir acompañado de un directorio llamado como el nombre del archivo del documento Markdown; dentro de éste, deberán estar las imágenes o archivos. Ejemplo:

  ejemplo-de-nombre-1.md
  +---- assets
        +---- ejemplo-de-nombre-1
             |---- imagen-1.png
             |---- imagen-2.png
             |---- imagen-3.png

• La primera versión del documento debe tener como status Draft (solo se cambiará de estatus cuando esté autorizado)
• Nunca se deben incluir usuarios, contraseñas, urls o cualquier otro dato real (incluidos los datos del ambiente de desarrollo)
• En caso de requerir una categoría nueva, se deberá solicitar que se agregue antes de su publicación.

Las categorias por default de Codelabs son:

Además de los agregados por default, se agregaron las siguientes categorías para el CONACyT:

A continuación se muestra un ejemplo sencillo de un Codelab en Markdown (también es posible verlo como un Codelab real).

    summary: How to Write a Codelab
    id: how-to-write-a-codelab
    categories: Sample
    tags: medium
    status: Published 
    authors: Zarin
    Feedback Link: https://zarin.io

    # How to Write a Codelab
    <!-- ------------------------ -->
    ## Overview 
    Duration: 1

    ### What You'll Learn 
    - how to set the amount of time each slide will take to finish 
    - how to include code snippets 
    - how to hyperlink items 
    - how to include images 
    - other stuff

    <!-- ------------------------ -->
    ## Setting Duration
    Duration: 2

    To indicate how long each slide will take to go through, set the `Duration` under each Heading 2 (i.e. `##`) to an integer. 
    The integers refer to minutes. If you set `Duration: 4` then a particular slide will take 4 minutes to complete. 

    The total time will automatically be calculated for you and will be displayed on the codelab once you create it. 

    <!-- ------------------------ -->
    ## Code Snippets
    Duration: 3

    To include code snippets you can do a few things. 
    - Inline highlighting can be done using the tiny tick mark on your keyboard: "`"
    - Embedded code

    ### JavaScript

    ```javascript
    { 
      key1: "string", 
      key2: integer,
      key3: "string"
    }
    ```
    
    ### Java

    ```java
    for (statement 1; statement 2; statement 3) {
      // code block to be executed
    }
    ```

    <!-- ------------------------ -->
    ## Hyperlinking and Embedded Images
    Duration: 1
    ### Hyperlinking
    [Youtube - Halsey Playlists](https://www.youtube.com/user/iamhalsey/playlists)

    ### Images
    ![alt-text-here](assets/how-to-write-a-codelab/puppy.jpg)

    <!-- ------------------------ -->
    ## Other Stuff|
    Duration: 1

    Checkout the official documentation here: [Codelab Formatting Guide](https://github.com/googlecodelabs/tools/blob/master/FORMAT-GUIDE.md)

Si se quiere tener un ambiente local donde poder previsualizar los borradores de los Codelabs, se puede seguir este tutorial.

Para más detalles sobre la estructura del Codelab, se puede consultar la guía de formato para Codelab

Si se requiere aprender sobre los archivos Markdown, se puede leer esta guía básica de sintaxis markdown.