Escribiendo posts: practicando con Quarto

(5ª parte del taller Mi primer blog con Quarto)

Autor

Afiliación

Pedro J. Pérez

Universitat de València

Fecha de Publicación

24 de noviembre de 2022

Contexto

Tutorial preparado para el taller Mi primer blog con Quarto impartido en Córdoba (Spain) durante el I Congreso & XII Jornadas de Usuarios de R, 23-25 de noviembre de 2022.
El taller está pensado para realizar con R. Se utilizará el IDE RStudio y Quarto. Se recomienda tener instaladas versiones recientes de los 3 programas
Este tutorial es sólo una parte del taller. El taller completo está aquí.

Recapitulación

En esta quinta parte del taller veremos como escribir nuestros posts con Quarto.
Las anteriores secciones del taller son:
1. Intro: se presenta el taller
2. Creación de un blog (básico) con Quarto: vimos como crear y alojar un blog básico con RStudio y Quarto.
3. Tuneado básico del blog: modificamos ligeramente los ficheros _quarto.yml, index.qmd, about.qmd y styles.css.
4. Workflow: ¿cómo crear un post?: vimos como generar nuevos posts para nuestro blog.

¿Qué haremos en este tutorial?

Aprender a escribir nuestro posts con Quarto: con ficheros .qmd
Repasaremos las 3 partes de los documentos .qmd: yaml, texto, chunks
Además veremos: layout
Aprender a utilizar algunos truquillos de Quarto

Advertencia

Voy a suponer que los asistentes al taller, y posibles lectores de estos tutoriales, conocen Rmarkdown y han escrito algún documento .Rmd. En ese caso, el paso de .Rmd a .qmd es sencillo.

En cualquier caso, aquí tienes unas FAQ’s para usuarios de .Rmd que se preguntan si pasarse a Quarto, y aquí unas slides sobre las diferencias entre .qmd y .Rmd.

Aquellos que no sepan qué es Rmarkdown pueden empezar por aquí o aquí.

En el tutorial anterior aprendimos a generar nuevos post para nuestro blog. Ahora aprenderemos a escribir esos post: veremos las posibilidades que nos ofrece Quarto a la hora de escribir y formatear nuestros posts.

1 Escribiendo con Quarto

En el tutorial anterior creamos un nuevo post en la carpeta ./posts/my-primer-post/. En realidad ese post es idéntico al primero (welcome) ya que sencillamente hicimos un copy-paste. Ahora sí que vamos a modificar el contenido (yaml/texto/chunks) del post para aprender algunos truquillos sobre Quarto.

Ya sabemos que la carpeta ./posts/my-primer-post/ contiene dos archivos. El importante es index.qmd que es el archivo que genera el post. Veámoslo:

Los ficheros .qmd tienen 3 partes: YAML, texto y chunks de código. Vamos a verlas una a una.

2 YAML

El encabezamiento o YAML, se utiliza para fijar determinadas opciones y metadatos de nuestro documento¹.

Una idea importante a recordar es que estamos trabajando con un Qproject. Trabajar con un Qproject tiene ventajas², entre ellas:

poder procesar todos los archivos con un solo comando: quarto render <myproject>
la posibilidad de “freeze rendered output”
la posibilidad de redireccionar los documentos de salida (output) a otro directorio
posibilidad de compartir la configuración del YAML para múltiples documentos. Los metadatos compartidos se pueden definir tanto a nivel de proyecto como a nivel de directorio.

Esta última ventaja, la posibilidad de compartir opciones de metadatos YAML en varios documentos, es importante ahora, porque nos da diferentes posibilidades para especificar el YAML de nuestros documentos o posts.

2.1 El `yaml` de un post

En un post se pueden especificar opciones YAML de 3 formas/niveles:

Nivel proyecto: todos los Qprojects contienen un archivo de configuración llamado _quarto.yml, de forma que, todo documento que se procese (render) dentro del proyecto, heredará automáticamente los metadatos definidos en _quarto.yml.
Nivel carpeta: si en una carpeta existe un documento _metadata.yml, los documentos de esa carpeta tendrán automáticamente las opciones definidas allí. La carpeta /posts/ de un blog suele tener un archivo _metadata.yml.
Nivel documento: En el yaml del propio post o documento .qmd

De esta forma, potencialmente, un post puede recibir opciones de YAML desde los 3 niveles. Si hay conflictos prevalecen las opciones del nivel documento, luego nivel carpeta y finalmente nivel proyecto.

Los blogs se publican en formato html, de forma que, aquí y aquí tienes la documentación oficial de Quarto con las principales opciones que se pueden fijar con el YAML para documentos html.

Es imposible repasar todas las opciones de YAML en el taller, veremos solamente algunas. Para ello, creo que la forma más operativa consistirá en mostrar ejemplos de ficheros .yml y revisar su contenido. Por ejemplo veamos las opciones YAML que tiene ahora nuestro blog:

Opciones YAML de nuestro blog

Abajo el contenido del fichero _quarto.yml tal y como lo tenemos ahora en nuestro blog. Solo he añadido 3 comentarios para diferenciar entre secciones:

Abajo el, contenido del fichero ./posts/_metadata.yml. Afectará a todos los ficheros .qmd que haya en la carpeta ./posts/

2.2 Yaml nivel proyecto

En el fichero _quarto.yml se especifican opciones y metadatos que afectaran a todos los documentos del proyecto. En el caso que nos ocupa (un Qproject para crear una web/blog) allí se suelen especificar metadatos acerca de 3 aspectos:

Funcionamiento del Qproject
Estructura de la web
Formato de salida de los documentos

2.2.1 Funcionamiento del Qproject

Estas opciones acerca del funcionamiento del Qproject, se especifican en el fichero _quarto.yml (nivel proyecto).

# 1/ Opciones referentes al proyecto ----------------------------
project:
  type: website
  output-dir: docs    #- podemos cambiar la carpeta donde se redirige el output (.html)
  # execute-dir: project    #- cambiar el render directory: https://quarto.org/docs/projects/code-execution.html#working-dir

Como vemos, podemos cambiar:

la carpeta donde se generará el output del proyecto (linea 4: output_dir : docs).
el directorio en el que se procesan los .qmd (linea 5: execute-dir: project). Los ficheros .qmd se procesan habitualmente en el directorio en el que residen pero puedes cambiarlo al directorio principal del proyecto³. Aquí documentación oficial sobre distintos aspectos de los Qprojects y sus opciones de configuración

2.2.2 Estructura de la web

Ya vimos algunas opciones en el 2º tutorial, veremos algunas más, pero será en el 7º tutorial. Como ejemplo, podríamos modificar esa sección de _quarto.yml para dejarla como:

#- 2/ Opciones referentes a la estructura de la web -----------------
website:
  title: "Mi blog (aún en pruebas)"
  favicon: profile.jpg
  #site-url: https://....
  #repo-url: https://....
  open-graph: true #-https://quarto.org/docs/websites/website-tools.html#twitter-cards
  twitter-card:
    creator: "@tu-usuario-twitter"
    card-style: summary_large_image
  navbar:
    logo: "profile.jpg"
    #background: primary    #- pink
    right:
      - text: "About me"
        href: about.qmd
      - icon: github
        href: https://github.com/<tu-usuario-github>
      - icon: twitter
        href: https://twitter.com/<tu-usuario-twitter>
      - icon: envelope
        url: "mailto:<tu-mail@uv.es>"
    left: 
      - icon: house-door
        href: index.html
      - text: "Docencia"
        href: docencia.qmd
  page-footer:
    left: "© 2022 Pedro J. Pérez"
    center: "Hecho con [Quarto](https://quarto.org)"
    right:
      - icon: github
        href: https://github.com/<tu-usuario-github>
      - icon: twitter
        href: https://twitter.com/<tu-usuario-twitter>
      - icon: envelope
        url: "mailto:<tu-mail>@uv.es"

Como ves, se añadirían elementos como:

Un pie de página (lineas 28 a 37)⁴
Hemos añadido un elemento a la navbar concretamente el icono Home (lineas 24 y 25). La documentación oficial para elementos de navegación está aquí
Elementos de redes sociales como un favicon (linea 4), el url de la web y del repo en Github (lineas 5 y 6) y más elementos de redes sociales (lineas 7 a 10). La documentación oficial para estos elementos está aquí

2.2.3 Formato de salida de los documentos

En un blog/web el formato de salida es siempre .html; sin embargo podemos especificar otras opciones como por ejemplo sí los documentos (o páginas de la web, o post del blog) tienen un índice flotante, etc…, etc ….

#- 3/ Opciones referentes al formato de salida  ---------------------
format:
  html:
    theme: flatly  
    css: styles.css
    toc: true
    highlight-style: a11y

Tarea 5.1

Bien, una vez hemos repasado las principales opciones referentes a _quarto.yml, vamos a incorporar esas modificaciones a nuestro blog.

Tarea 5.1: Modificar _quarto.yml

Tenemos que dejar el archivo _quarto.yml así:

# 1/ Opciones referentes al proyecto ----------------------------
project:
  type: website
  output-dir: _site    
 
#- 2/ Opciones referentes a la estructura de la web -----------------
website:
  title: "Mi blog (aún en pruebas)"
  navbar:
    logo: "profile.jpg"
    #background: "#CCCCFF"    #- {“primary”, “secondary”,  “danger”, “warning”, “light”, “dark”, or hex color} (el backgroung de la navbar)
    right:
      - text: "Mi blog"
        href: blog.qmd
      - icon: github
        href: https://github.com/<tu-usuario-github>
      - icon: twitter
        href: https://twitter.com/<tu-usuario-twitter>
      - icon: envelope
        url: "mailto:<tu-mail@uv.es>"
    left: 
      - icon: house-door
        href: index.html
      - text: "Docencia"
        href: docencia.qmd
      #- text: "Docencia"
        #href: docencia.qmd
  page-footer:
    left: "© 2022 Pedro J. Pérez"
    center: "Hecho con [Quarto](https://quarto.org)"
    right:
      - icon: github
        href: https://github.com/<tu-usuario-github>
      - icon: twitter
        href: https://twitter.com/<tu-usuario-twitter>
      - icon: envelope
        url: "mailto:<tu-mail>@uv.es"

#- 3/ Opciones referentes al formato de salida  ---------------------
format:
  html:
    #- https://quarto.org/docs/output-formats/html-themes.html
    theme: flatly  
    css: styles.css
    toc: true
    #- https://quarto.org/docs/output-formats/html-code.html#highlighting
    highlight-style: a11y

2.3 Yaml nivel carpeta

Como ya sabemos, si en una carpeta hay un fichero _metadata.yml, todos los documentos .qmd que se procesen en esa carpeta se verán afectados por esas opciones. Veamos como tenemos ahora mismo ese archivo.

Abajo el, contenido del fichero ./posts/_metadata.yml de nuestro blog

Tarea 5.2

Vamos a cambiar un poco el archivo ./posts/_metadata.yml, simplemente cambiaremos el valor de freeze: true a freeze: auto lo que hará que cuando hagamos un render global del proyecto, solo se vuelvan a ejecutar los archivos que hayan visto cambiado su contenido, el resto no se volverán a procesar.

Tarea 5.2: Modificar ./posts/_metadata.yml

Tenemos que dejar el archivo ./posts/_metadata.yml así:

# IMPORTANTE: options specified here will apply to all posts in this folder

# freeze: controla la ejecución de los .qmd durante un global project render
# https://quarto.org/docs/projects/code-execution.html#freeze)
freeze: auto   #- {false, true, auto}

#- Quarto incluye un title-block al principio de los artículos con elementos como: title, subtitle, authors, date, doi, and abstract.

# title-block-banner: pone un banner en el title-block: pondrá el title, subtitle, description, y categories dentro del banner
# https://quarto.org/docs/authoring/title-blocks.html#title-banners
title-block-banner: true  #- {true, false, "#FFDDFF",  "image.jpg"}

# title-block-style: modifica el estilo del title-block
# https://quarto.org/docs/authoring/title-blocks.html
title-block-style: default #- {default, plain, none}

# tb se puede especificar el color del texto dentro del banner
title-block-banner-color: red

IMPORTANTE: las opciones que especifiques en _metadata.yml afectarán a todos los .qmd de la carpeta.

freeze (linea 5): {false, true, auto} controla la ejecución de los .qmd durante el procesado completo del Qproject. Documentación aquí.
title-block-banner (linea 11): {true, false, "#FFDDFF", "image.jpg"} controla la presencia y apariencia de los “banners” para dar más importancia a los títulos de los posts. Puedes controlar el color, incluso poner una imagen. Documentación aquí.
title-block-style (linea 15): {default, plain, none} modifica el estilo del title-block
title-block-banner-color(linea 18): {black, "#FFDDFF"} controla el color del título del post

2.4 Yaml nivel documento

Como dijimos, también podemos especificar metadatos y opciones para un documento .qmd en el encabezamiento del documento. Lógicamente esas opciones sólo afectarán a ese documento.

Tarea 5.3

Probemos a cambiar el yaml o encabezamiento de ./posts/my-primer-post/index.qmd

Tarea 5.3: Modificar encabezamiento de ./posts/my-primer-post/index.qmd

Tenemos que dejar el archivo ./posts/my-primer-post/index.qmd así:

---
title: "Mi primer post con Quarto"
description: |
  Estoy aprendiendo Quarto
author:
  - name: Pedro J. Pérez
    url: https://www.wikidata.org
    affiliation: Universitat de València
    affiliation-url: https://www.uv.es
    orcid: 0000-xxxx
date: "2022-10-25"
categories: [R, quarto]
#title-block-banner: true #- {true, false }
title-block-banner: thumbnail.jpg
title-block-banner-color: green
---

Este es mi **primer post** con Quarto!!!!

```{r}
sqrt(2 + 2)
```

Voy a poner una imagen:

![](thumbnail.jpg)

Acabé con mi primer post. FIN

Sustituye thumbnail.jpg por otro archivo
Vuelve a regenerar el blog: Build > Render Website

3 Texto

El texto (o narrativa) de un documento .qmd se escribe, al igual que en los documentos .Rmd en markdown. Aquí la documentación oficial de Quarto.

No lo vamos a practicar ahora. Lo haremos (un poco) luego cuando hagamos un post de ejemplo.

3.1 Sintaxis básica de `markdown`

Aquí puedes ver o recordar la sintaxis básica, las principales reglas para escribir en markdown.
Como ejemplo:

4 Chunks de código

Los chunks de código en .qmd también tienen un comportamiento similar a lo que ocurría en los chunks en documentos .Rmd. La documentación oficial está aquí

4.1 Diferencias con .Rmd

Las principales diferencias son:

En .Rmd las opciones de los chunks se podían especificar de forma global en un chunk inicial (generalmente llamado setup) y a nivel individual en cada uno de los chunks; mientras que ahora, con .qmd, las opciones de los chunks se pueden especificar globalmente en el YAML y a nivel individual en cada uno de los chunks.

Extensiones: mi setup chunk

Cuando usaba .Rmd este era habitualmente mi chunk de setup

En los chunks individuales ahora se se utiliza la sintaxis YAML (key: value) en lineas dentro del chunk que empiezan con #|. Por ejemplo:

Las principales opciones son: echo, eval, warning, error, output e include. Aquí la documentación oficial.
echo, además los típicos true y false, ahora incorpora un nuevo valor fenced que facilita mostrar las marcas de los chunks en el documento final. Documentación aquí. Los llamados unexecuted Blocks, documentación aquí, también facilitan mostrar las marcas de los chunks en el documento de salida.
Además, si usamos knitr para ejecutar los chunks, entonces podemos usar todas las opciones nativas de knitr, como: collapse, fig.width, comment, etc … Más información aquí. Un ejemplo:

4.2 Más opciones para los chunks

La documentación oficial la tienes aquí.

Puedes hacer folding code

Muéstrame el código

```{r, eval = FALSE}
#| code-fold: true #- {true, false, show}
#| code-summary: "Muéstrame el código"
2 + 2
```

Si el código es muy largo, puedes usar code-overflow: wrap y code-overflow: scroll

```{r, eval = FALSE}
#| code-overflow: wrap
2 + 2  +2 + 2 + 2 + 2  +2 + 2 + 2 + 2  + 2 + 2 + 2 + 2  + 2 + 2 + 2 + 2  + 2 + 2 + 2 + 2  +2 + 2
```

Puedes hacer que se muestre el número de linea

```{r, eval = FALSE}
#| code-line-numbers: true
2 + 2 
4 + 4
```

5 Elementos para escribir

5.1 Elementos básicos

Para escribir en Markdown, además de texto, tenemos los siguientes elementos básicos:

Links (documentación aquí)
Listas (documentación aquí)
Tablas (documentación aquí)
Código (documentación aquí)
Ecuaciones (documentación aquí). Editor de ecuaciones aquí o aquí.
Imágenes (documentación aquí) y sus opciones

El editor visual facilita la introducción de estos elementos en tus documentos. En esta charla de Mine Çetinkaya-Rundel se aprecia fácilmente la utilidad del editor visual.

5.2 Más elementos para “escribir”

Además de los elementos básicos de escritura que nos ofrece la sintaxis básica de markdown, Quarto nos ofrece más posibilidades. Por ejemplo:

Imágenes (documentación aquí) y sus opciones
Callout blocks (documentación aquí)
Divs & spans (documentación aquí)
Layout (documentación aquí y aquí)
Extensiones (documentación aquí) . Listado de extensiones oficiales aquí

Veamos algunos de estos elementos con un poco de detalle. Después lo recordaremos con una Práctica.

5.3 Veamos algunos

Layouts

Además de yaml, texto y chunk, para escribir con Quarto conviene conocer la estructura o layout de los artículos que se generan con él.
Los “artículos” tienen un body, un margin y un área para las sidebars, que en nuestro caso contiene el TOC⁵.
Usando divs se puede hacer que alguna sección de nuestra página ocupe un espacio mayor al habitual; es decir, mayor al espacio habitualmente reservado para el body.
Veamos las posibilidades que tenemos de layout con este post

Extensiones

Una de las novedades de Quarto es la posibilidad de usar extensiones. Las extensiones se escriben en lenguaje Lua.
Para ver como instalar y usar extensiones vamos a ir, otra vez, a otro de los post del blog del taller: concretamente aquí

Imágenes

Conocemos la sintaxis básica para insertar imágenes ![](<ruta-a-imagen>); ahora veremos posibilidades más avanzadas
Veamos como insertar imágenes con este post del blog del taller.

6 Resumen

Resumen (tutorial nº 5)

La quinta parte del taller se ocupa de la escritura de posts para el blog.
Los posts se han de escribir en formato .qmd; por lo tanto, se repasan los fundamentos “teóricos” necesarios para escribir este tipo de documentos.
Nos apoyamos en nuestro conocimiento previo de la sintaxis Rmarkdown.
Se repasan las posibilidades de configurar los documentos por medio de los 3 niveles de YAML que pueden afectar a un documento.
Los 3 YAML’s son: Nivel proyecto (_quarto.yml), nivel carpeta (_metadata.yml) y nivel documento (en el propio encabezamiento del archivo)
El texto en ficheros .qmd es muy similar al de los documentos .qmd. Aparecen algunos elementos nuevos como los Call-outs.
El código sí presenta novedades: nueva sintaxis con #| y posibilidad de determinar opciones de los chunks en el YAML.
Para poder escribir en .qmd hay que practicar. Lo haremos con una tarea donde veremos, entre otras cosas:
- Algunas de las opciones de layout.
- Ver como instalar y usar extensiones.
- Opciones avanzadas para insertar imágenes.

7 Práctica

En esta sección dedicaremos un tiempo a la práctica libre para la creación y escritura de un post. Para ello te ofrezco más abajo una plantilla con la que elaborar un post. la plantilla tiene una serie de tareas/retos que has de realizar/superar.

Usaremos un ejemplo para practicar la sintaxis y nuevas posibilidades de Quarto a la hora de generar documentos .html: o sea, para escribir posts para nuestro blog.

Práctica 5.1: Crear un post para tu blog con la siguiente plantilla.

Vamos a crear un nuevo post para practicar algunos de los elementos de escritura que hemos visto. Para ello:

Crea una nueva subcarpeta en la carpeta ./posts/. Por ejemplo llámala: ./posts/my-segundo-post y copia allí los documentos que haya en la carpeta de otro blog. Es decir, en la nueva subcarpeta que has creado debe haber un fichero index.qmd y una imágen thumbnail.jpg.
Sustituye el contenido del archivo index.qmd por el contenido del siguiente chunk y haz un render de ./posts/my-segundo-post/index.qmd para ver como quedaría una vez procesado.

Contenido para sustituir en `./posts/my-segundo-post/index.qmd`

---
title: "Mi Segundo post con Quarto"
author: "Nosotros"
date: 2022-10-25
categories: [R, quarto, ejemplos]
image: "thumbnail.jpg"
#subtitle: | 
#  Practicando con Quarto
description: |
  Estamos viendo algunos elementos para escribir con Quarto.
---

Este ya es mi segundo post con Quarto. En él voy a hacer lo siguiente:


## Insertar 2 imágenes side-by-side


## Inserta un tweet


## Inserta un `tab-set`


## Inserta un call-out


## Inserta un gráfico en el margen


<br>

Prueba superada!!


Acabé con mi segundo post. FIN

Las soluciones a la Práctica están aquí

Notas

El YAML será procesado varias veces durante el procesado del documento: es leído por Quarto, knitr y Pandoc e influirá en el resultado final, pudiendo afectar al código, al contenido y al procesado del documento↩︎
Puedes ver la documentación oficial de Quarto sobre proyectos aquí ↩︎
Aunque yo no lo haría: estoy muy acostumbrado a que el directorio de trabajo de los .Rmd sea la carpeta donde residen↩︎
Puedes ver un ejemplo de cómo quedaría el pie de página en la web del taller, aquí ↩︎
Además, el layout puede venir afectado por la opción page-layout: custom #- {article, full, custom}↩︎

Reutilizar

https://creativecommons.org/licenses/by/4.0/deed.es

1 Escribiendo con Quarto

2 YAML

2.1 El yaml de un post

Opciones YAML de nuestro blog

2.2 Yaml nivel proyecto

2.2.1 Funcionamiento del Qproject

2.2.2 Estructura de la web

2.2.3 Formato de salida de los documentos

Tarea 5.1

2.3 Yaml nivel carpeta

Tarea 5.2

2.4 Yaml nivel documento

Tarea 5.3

3 Texto

3.1 Sintaxis básica de markdown

4 Chunks de código

4.1 Diferencias con .Rmd

4.2 Más opciones para los chunks

5 Elementos para escribir

5.1 Elementos básicos

5.2 Más elementos para “escribir”

5.3 Veamos algunos

Layouts

Extensiones

Imágenes

6 Resumen

7 Práctica

Contenido para sustituir en ./posts/my-segundo-post/index.qmd

Notas

Reutilizar

2.1 El `yaml` de un post

3.1 Sintaxis básica de `markdown`

Contenido para sustituir en `./posts/my-segundo-post/index.qmd`