Migrar el blog de ixpantia de Rmarkdown Distill a Quarto

Mejores prácticas
R

En RStudio::Conf 2022 hubo mucha atención para una nueva herramienta creada por el equipo de Posit llamada Quarto. Es la una nueva implementación de las ideas detras de Rmarkdown que ofrece un entorno de trabajo para programación literaria mas coherente. Aqui describimos como migramos nuestro blog de Rmarkdown a Quarto.

Author
Affiliation
Frans van Dunné

ixpantia

Published

August 1, 2022

Acompañamos en iniciativas y proyectos de ciencia de datos, ingeniería e infraestructura. Visita nuestra página ixpantia y contáctanos.

El blog de ixpantia en Quarto

De Rmarkdown a Quarto

Desde hace un par de años comenzamos a escribir el blog de ixpantia, y ya que usamos Rmarkdown en muchos de nuestro proyectos era natural usar Distill para Rmarkdown. Pero uno de los grandes anuncios de la semana pasada en la conferencia Rstudio::Conf fue que Quarto esta listo para entrar a producción. La otra Fue que RStudio se llama Posit de ahora en adelante.

Rmarkdown no va a desaparecer en mucho tiempo. Es una tecnología madura que se ha demostrado útil a lo largo del tiempo para agilizar el desarrollo de productos de datos y facilitar la comunicación de resultados. El equipo detrás del desarrollo de Quarto lo presenta como la versión mejorada de Rmarkdown. A como lo entendemos en este momento las ventajas son.

  1. Ofrece todo lo bueno de Rmarkdown fuera de R, en particular para Python, Julia y Observable (JavaScript). Esta ventaja se centra en gran parte en la flexibilidad de escoger el formato de salida, y independencia de R para correrlo. Quarto se puede usar desde cualquier editor, y no solo RStudio.
  2. Mayor consistencia entre los diferentes formatos de salida. Hay mayor coherencia en como definir la salida, lo que permite más fácil re-uso de contenido en diferentes formatos, incluyendo este blog.
  3. Trabar con un un enfoque en “programación literaria” donde combinamos código con texto descriptivo, en combinación con sistemas de gestión de código da mucha flexibilidad a la hora de colaborar.

La migración

Empezamos con el blog de ixpantia con este formato.

Screenshot del blog de ixpantia en Rmarkdown Distill

Y de allí damos los pasos para cambiarlo a Quarto. Hay documentación extensa del Quarto Blog y aqui abajo la usamos para hacer la migración del blog en Distill a Quarto. En el proceso podemos ver en detalle las diferencias.

  1. Asegúrate que tienes una copia de respaldo de toda la carpeta que contiene tu blog.

  2. Borra la carpeta _site

La versión anterior esta renderizada en la carpeta _site y nos dimos cuenta de que tener la versión vieja puede dar a errores extraños. Mejor borrarla de una vez (esta se vuelve a crear automáticamente en el primer render que haces).

  1. Cambia la definición del blog

En Quarto la definición de la publicación - la receta para lo que se ha de presentar, por asi decirlo - esta en el archivo _quarto.yml. Para arrancar renombramos los siguientes archivos y carpetas.

  • _site.yml –> _quarto.yml
  • _posts.yml -->posts`
  1. Cambia los nombres de .Rmd a .qmd.

La nueva extensión de los archivos es qmd (Quarto markdown). Con simplemente cambiar el nombre el documento Rmarkdown original ya es usuable. Como hay que hacerlo recursivo usamos zsh zmv.

autoload zmv
zmv -n '(**/)(*).Rmd' '$1$2.qmd'

En la carpeta posts tenemos que hacer un poco más de trabajo. En cuarto, cada una de la publicaciones se escribe en un archivo llamado index.qmd. El titulo lo distinguimos por los nombres de las carpetas. Para estar seguro de hacer esto bien lo hicimos a mano. Esto de hecho nos permitió limpiar algunas carpetas que no debian estar alli (con render previos que se colaron en el repositorio). Y además vimos que en un par de casos existia el html, pero no estaba el rmarkdown y lo pudimos buscar en la historia del proyecto para restaurarlo.

  1. Reconfigurar el Blog

Este paso es mas manual y puede ser diferente para tu blog. El archivo yml que describe como presentar un blog cambia. En nuestro caso teniamos para distill.

---
title: "ixpantia blog"
description: |
  Impulsamos ciencia de datos en su organización
site: distill::distill_website
listing: posts
---

Y esto lo llevamos a

---
title: "ixpantia blog"
description: |
  Impulsamos ciencia de datos en su organización
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
  sort-ui: false
  filter-ui: false
page-layout: full
title-block-banner: true
---

Los encabezados de cada articulo se hacen más claros, pero hay un par de detalles que requiere atención porque no es tan obvio que tienen que cambiar.

Este era el encabezado con Distill

---
title: "¿Quiero aprender ciencia de datos, ahora que?"
description: |
   ¿Por donde comenzar a aprender ciencia de datos? No es una pregunta fácil de
   responder, pero en este post tratamos de indicar por donde mejor comenzar o
   seguir con tu camino.
author:
  - name: Frans van-Dunné
    url: https://fransvandunne.com
    affiliation: ixpantia
    affiliation_url: https://www.ixpantia.com
date: 03-05-19
creative_commons: CC BY-NC
preview: images/pixabay_nature2592000.jpg
twitter:
  site: "@ixpantia"
  creator: "@fransvandunne"
output:
  distill::distill_article:
    self_contained: true
---

El mismo encabezado ahora se ve asi.

---
title: "¿Quiero aprender ciencia de datos, ahora que?"
description: |
   ¿Por donde comenzar a aprender ciencia de datos? No es una pregunta fácil de
   responder, pero en este post tratamos de indicar por donde mejor comenzar o
   seguir con tu camino.
author:
  - name: "Frans van Dunné"
    url: "https://cr.linkedin.com/in/fransvandunne"
    affiliations: 
      - name: "ixpantia"
        url: "https://www.ixpantia.com"
date: 03-05-19
licence: "CC BY-NC"
image: images/pixabay_nature2592000.jpg
---

Los siguientes detalles me costaron un poco de esfuerzo encontrar.

  1. El formato de autoria y afiliación cambio. Dentro del bloque de autor ahora hay que incluir el bloque de afiliaciones, con su propio tag de nombre y url.
  2. El formato de las imagenes de prevista en la pagina principal (thumbnails) cambio tambien. Ya no es preview pero cambio a image, y si no haces el cambio no vas a ver la imagen en la pagina principal.
  3. El formato de los metadatos tiene varios cambios - como aqui arriba la licencia, pero con eso se amplio para incluir nuevos parametros.
  4. La referencia a twittter ahora es para todo el blog y se coloca en _quarto.yml.

Mejoras

Pronto después de la migración inicial fui viendo formas de simplificar el website. Por ejemplo, ya no es necesario tener un pedacito de html con el pie de la pagina (footer). Lo puedes incluir directamente en el archivo _quarto.yml.

  body-footer: 
     Este blog lo mantiene el equipo de [ixpantia](https://www.ixpantia.com) y 
     la comunidad de gente interesada en datos de la cual estamos contentos de formar parte
    ¿Tienes una idea para publicar algo aquí? ¡Escríbenos! Estamos siempre interesados en material e ideas nuevas.
    © 2019-2022 ixpantia

Con lo de arriba ojalá puedas tener una primera indicación de los cambios que son necesarios para tu blog. De nuestro lado la experiencia fue buena, estamos acomodándonos para migrar nuestra documentación y procesos de análisis a Quarto. La expresividad y consistencia de los encabezados yaml de Quarto parecen a primer vista de ser una gran mejora.

Sobre Posit e ixpantia

ixpantia es un partner certificado de Posit, lo que significa que podemos vender las licencias y mantener las instalaciones de los productos profesionales de Posit como lo son RStudio Workbench, RStudio Connect y Rstudio Package Manager. Si usted tiene interés en alguno de estos productos, o si busca acompañamiento para lograr que su equipo saque mas provecho de los mismos no dude en contactarnos.

Este blog lo mantiene el equipo de ixpantia y la comunidad de gente interesada en datos de la cual estamos contentos de formar parte ¿Tienes una idea para publicar algo aquí? ¡Escríbenos! Estamos siempre interesados en material e ideas nuevas. © 2019-2022 ixpantia