Mi primer blog con Quarto (y Rmd)

(Web del taller aquí)

Pedro J. Pérez

Universitat de València

24/11/22

Bienvenidos al taller!! 🖖🌹

Sobre mi (Pedro J. Pérez)



Intro

Estructura del taller


  1. Intro: presentación del taller, visionado de blogs y ¿qué es Quarto? (15 min)


  1. Creación de un blog básico: mi blog en 3 minutos (10 min)

  2. Tuneado básico del blog (15 min). Práctica (15 min)

  3. Convirtiendo el blog en una web personal (5 min)


  1. Workflow: creando posts (5 min)

  2. Escribiendo un post con Quarto (15 min). Práctica (15 min)


  1. Tuneado: mejorando la web (14 min)
  1. Gestión y publicación de la web/blog (1 min)

Objetivo(s) del taller


  • Aprender a hacer websites/blogs con Quarto


  • Aprender sobre Quarto mientras vamos creando una web/blog


  • Que salgáis todos con el bosquejo y la intención de hacer una web/blog!!


  • … y, si puede ser, pasar un buen rato 🙂 mientras aprendemos

Beneficios de tener un blog


  • Se aprende mucho!!

  • Es fácil (pocas barreras de entrada si usas Rmarkdown)

  • Es divertido

  • Registrar análisis que haces que de otra forma olvidarías

  • Portafolio y contactos

  • Productive procrastination (!!)

(Discursos más elaborados aquí o aquí )


Importante:

  • El blog no tiene que ser perfecto. Mejor empezar con un blog sencillo
  • Los posts tampoco tienen porqué estar perfectos, así que no hay que tener miedo a escribir!!

Estructura de una web

HEADER/Navbar


TITLE-block banner




ARTICLE





Footer

Ejemplos de blogs (hechos con Quarto)


Más opciones:

¿Qué es Quarto?

Quarto is a multi-language, next generation version of R Markdown, with many new features and capabilities.


Puedes ver este video de 100 segundos

¿Qué es Quarto?


  • Un nuevo sistema de publicación científica y técnica de código abierto basado en Pandoc
  • Muy parecido a Rmarkdown, pero … no requiere R. Soporta lenguajes como Phyton, Julia y Observable.

  • Unifica funcionalidades de varios paquetes del entorno Rmd como xaringan, bookdown, blogdown , …

  • Es … la “segunda generación de Rmarkdown”

  • Quarto utiliza Knitr para ejecutar el código R; así que es capaz de procesar también los ficheros .Rmd sin modificarlos


  • Quarto no es un paquete, es un programa independiente, un CLI

Ventajas de Quarto

  • Proyecto en desarrollo activo … mientras que Rmarkdown it’s not going away pero …

  • Unifica algunas de las funcionalidades de Rmarkdown

  • Por ejemplo: Cross references, Call-outs, Advanced Layout (tb para imágenes), Extensiones, Interactividad, YAML inteligence, Quarto Pub, Divs, Spans

Setup para el taller


  • Vamos a trabajar con R (a través de RStudio) y Quarto

  • Si tienes RStudio 2022.07.1 +, ya tienes Quarto instalado

  • Instrucciones de instalación aquí.

  • Para descargar Quarto puedes ir aquí.


El taller está diseñado suponiendo que conocéis/usáis Rmarkdown

Refresh de Rmarkdown (.Rmd)

¿Qué es Rmarkdown? ¿Para qué sirve?

  • Un “entorno” para hacer informes/publicaciones/transparencias REPRODUCIBLES con R.

Is an authoring framework for data science, combining your code, its results, and your prose. R Markdown documents are fully reproducible and support dozens of output formats, like PDFs, Word files, slideshows, and more.


Una oda a Rmarkdown

  • How Rmarkdown changed my life: charla de Rob Hyndman sobre su proceso hasta llegar a usar Rmarkdown para hacer sus documentos científicos y webs.

Documentos .Rmd tienen 3 partes

  1. Encabezamiento (yaml header)
  2. Trozos de código R (R chunks)
  3. Texto (narratives)

Un ejemplo

source code

output

(I) El encabezamiento o “yaml header”

  • Se (suele) poner al ppio del documento, entre estas marcas: ---

  • En el yaml son MUY importantes los espacios y la indentación

  • Puedes aprender más sobre el yaml en el manual de Pandoc

Otro ejemplo de yaml

(IIa) Código R (chunks)

  • Para que knitr sepa qué partes del .Rmd es código R, deben ir dentro de estas marcas:

  • Por ejemplo:

  • Cuando knitr procese el chunk, lo interpretará como código R y ejecutará las instrucciones y mostrará en el documento final el output generado por el chunk.

(IIb) Chunks: diferencias con Quarto

  • Ahora se usa YAML style (echo: false).

  • Cada opción va en una linea que empieza por el “hash pipe”: #|

.Rmd

.qmd

(IIc) Chunks: diferencias con Quarto

  • No hace falta chunk inicial: con Quarto se pueden poner las opciones de chunk en el YAML

.Rmd

.qmd

(III) Texto (narrativa)

  • Todo lo que no es YAML o CHUNKS de código, es TEXTO.

  • El texto se escribe en Markdown (concretamente en Pandoc’s Markdown)


Sintaxis básica de markdown

  • Aquí puedes ver (o recordar) la sintaxis básica para escribir en markdown. Como ejemplo:

Cuando tengáis tiempo mirad este Workshop sobre Quarto. Awesome!!

Comenzamos el taller !!!! 💻🤞 💪🏼 💪🏼

Contexto

  • 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


Hay 3 formas de seguir el tutorial

  1. La forma recomendada: utilizando Quarto a través de RStudio

  2. Utilizar Quarto desde la Terminal y usar tu editor favorito (VScode …)

  3. Utilizar RStudio Cloud


1. Creación de un blog básico con Quarto

(1ª parte del tutorial)

¿Qué haremos en este tutorial?

  • Veremos de forma rápida el proceso de creación y la estructura de ficheros de un blog creado con Quarto. La documentación oficial está aquí.

  • Alojaremos el blog en Quarto Pub.

  • Será un blog básico pero completamente operativo. Ya tendremos tiempo de mejorarlo, o tunearlo, en las siguientes secciones del taller.

Tarea 1.1: Hemos de crear la carpeta que contendrá nuestro blog.

La carpeta la creará Quarto, pero tenemos 3 formas de hacerlo:


A) Crear la carpeta (o Qproject) desde RStudio

  • En RStudio sigue la siguiente ruta de menús:

    File > New Project > New Directory > Quarto Blog

  • Mejor si llamas a la carpeta: blog_prueba_00


B) Crear la carpeta desde la Terminal

  • Has de ejecutar desde la Terminal:

    quarto create-project blog_prueba_00 --type website --template blog


C) Usando un Qproject ya creado con RStudio Cloud

  • Tienes que ir aquí. Se abrirá Rstudio en el navegador con un Qproject llamado blog_prueba_00.

  • Has de tener cuenta en RStudio Cloud. Haz una copia permanente y trabaja sobre ella


De cualquiera de las 3 maneras acabaremos teniendo una carpeta con todo o necesario para crear un blog.

Contenido del Qproject

Los archivos importantes ahora son 3:

  • _quarto.yml: especifica la estructura (y apariencia) de la web

  • index.qmd : generará (y dará formato) a la “landing page” o Home. Esta página será un listado de páginas (un blog)

  • about.qmd : una de la páginas del blog


Tarea 1.2: Generación del blog

  • Ir al cuadrante superior-derecha de RStudio, pinchar en la pestaña Build y pinchar en Render Website.

  • De esta forma, se procesarán los archivos del Qproject y se creará el blog.

  • Podremos verlo en el cuadrante inferior-derecha de RStudio, concretamente en la pestaña Viewer.

Extensiones: formas alternativas de generar el blog

  • También podríamos haber generado el blog usando la Consola o la Terminal desde RStudio.

  • En ambos casos hay que estar en el Qproject “blog_prueba_00”; es decir, “blog_prueba_00” es el working directory

  • Desde la Terminal

    quarto render

  • desde la Consola de R

    install.packages("quarto")    
quarto::quarto_render("index.qmd")


Contenido del Qproject (tras procesar el blog)

  • Se han creado 2 subcarpetas: _site y _freeze

  • _site es la carpeta que contiene el blog.


Ver el blog en local

  • _site es la carpeta que contiene el blog. Veamos su contenido

  • La página principal (o Home) de nuestro blog es el archivo index.html.

  • El archivo index.html ha sido generado por el fichero index.qmd.

Tarea 1.3: Ver el blog

  • Enseguida publicaremos el blog en Quartopub, pero antes vamos a verlo en local.

  • Para ello solo tienes que pinchar en el archivo ./blog_prueba_00/_site/index.html

  • Ese fichero es el que contiene la “Landing Page” o “Home” de nuestro blog.

  • Como ves el blog es muy sencillo, solo tiene 2 páginas:

    • la Home Page (que consiste en un listado de posts)

    • la página About


Contenido de index.qmd

  • El archivo index.qmd genera index.html, la página principal (o Home) de nuestro blog

Extensiones: ver el contenido del archivo index.qmd

Contenido del archivo index.qmd que genera a index.html:

  • Como vemos, el archivo index.qmd no tiene contenido, sólo contiene un yaml o encabezamiento

  • Ese encabezamiento genera una lista (listing:) con los contenidos (con los ficheros .qmd) que haya en la carpeta posts.

  • Sí, has imaginado bien, en la carpeta posts es donde estarán los ficheros .qmd que generarán los posts

  • El resto del yaml son opciones para nuestro blog. Por ejemplo, sort: "date desc" ordenará el listado de post de más reciente a más antiguo.

  • Lo iremos viendo


Alojando el blog

Tarea 1.4: Alojar el blog en Quarto Pub

Para publicar nuestro blog en Quartopub sólo hay que:

  • teclear en la Terminal de RStudio (panel inferior-izquierda) lo siguiente:

    quarto publish quarto-pub

  • Tras ejecutar lo anterior, se te pedirá que autorices en la Terminal.

  • Después se abrirá el navegador, tendrás que logearte en Quarto Pub y volverás a autorizar. Además te preguntarán el nombre del blog.

  • Puedes ver aquí, como quedaría el blog una vez alojado en Internet.


Extensiones: el fichero _publish.yml

Si te fijas, tras haberse publicado el blog en “Quarto Pub”, se habrá creado un nuevo fichero en nuestro Qproject: es el fichero _publish.yml. En él solamente están los metadatos necesarios para publicar y actualizar nuestro blog.


Resumen (tutorial nº 1)

En este tutorial, la segunda parte del taller, hemos visto:

  • Como crear un Qproject con la estructura de carpetas y archivos necesaria para generar un blog básico

  • Hemos visto (de forma rápida) el contenido, los archivos, que hay en el Qproject.

  • El Qproject contiene 3 archivos que serán los importantes, los que trabajaremos en el próximo tutorial, concretamente: _quarto_yml, index.qmd y about.qmd

  • Hemos aprendido a generar el blog a través de RStudio, simplemente Build > Render Website

  • Hemos visto que el blog realmente se aloja en la carpeta _site y que la homepage es index.html

  • La homepage del blog es un listado de post (lógicamente, es un blog!!)

  • La homepage (index.html) es generada por el archivo index.qmd

  • El archivo index.qmd solo tiene yaml

  • Hemos publicado el blog en Quarto Pub


2. Tuneado básico del blog

(2ª parte del tutorial)

¿Qué haremos en este tutorial?

  • En esta segunda parte del taller vamos a mejorar/tunear un poco nuestro blog. Nos servirá para afianzar nuestro conocimiento de la estructura de ficheros del blog

  • En este tutorial nº 2, para hacer un tuneado básico del blog, modificaremos 3 archivos, concretamente los archivos: _quarto.yml, index.qmd y about.qmd. Iremos archivo por archivo

  • Finalmente modificaremos (un poco) el archivo styles.css

  • En el tutorial nº 6 se profundiza en el tuneado del blog


Archivo _quarto.yml

Contenido original de _quarto.yml

Así dejaremos el fichero _quarto.yml

Tarea 2.1: Modificar el contenido de _quarto.yml

  • Sustituye el contenido original del fichero _quarto.yml por el contenido del siguiente chunk.

  • Pon un título que te guste a tu blog (línea 5 title: "titulo-de-mi-blog")

  • Pon tu usuario de Github y cuenta de Twitter (lineas 12 y 14: href:)

  • Pon tu email (línea 16: href:)

project:
  type: website

website:
  title: "Mi blog (aún en pruebas)"
  navbar:
    logo: "profile.jpg"
    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: 
      - text: "Docencia"
        href: docencia.qmd
 
format:
  html:
    theme: flatly  
    css: styles.css
    toc: true
    highlight-style: a11y

Además:

  • lineas 17-19: añadimos la página/pestaña “Docencia” a la izquierda de la navbar
  • lineas 21-26: modificamos el theme, ponemos TOC a los documentos, …, CSS,

Tarea 2.2: Crear el archivo docencia.qmd

  • Podríamos crear el archivo docencia.qmd con cualquier contenido, incluso podría ser un documento sin contenido, PERO, mejor si lo creas con el siguiente contenido:
---
title: "Mi docencia"
---

Mi docencia es:

## curso 2021-2022

- [Econometría](/pdfs/econometria.pdf)

## curso 2022-2023

- [Algebra](/pdfs/econometria.pdf)

Tarea 2.3: Crear el archivo /pdfs/econometria.pdf

  • Como puedes ver, en el archivo docencia.qmd se hace referencia al archivo /pdfs/econometria.pdf. Si quieres que el link funcione, tienes que crear dentro del Qproject, la subcarpeta pdfs, y dentro de ella el archivo econometria.pdf.

  • Puede ser cualquier pdf, siempre que se llame econometria.pdf

Tarea 2.4: Volver a generar el blog

  • Una vez hechas las tareas 2 y 3, puedes crear de nuevo el blog con Build > Web page.

Archivo index.qmd

Contenido original de index.qmd

Así dejaremos el fichero index.qmd

  • De momento, solo vamos a hacer cambios en la segunda linea: cambiaremos el título.

  • Fíjate que es el título del listado de posts (del blog), no de la página web.

  • Fijaros que index.qmd es un archivo especial: “sólo tiene yaml”. Es el que genera el listado de posts


Tarea 2.5: Modificar el contenido de index.qmd

  • He cambiado la segunda linea (title:) para poner un nombre a la página con el listado de posts.

  • También podemos añadir una descripción (con description:).

---
title: "Mi listado de post"
description: |
  Estoy tratando de hacer mi blog
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
  sort-ui: false
  filter-ui: false
page-layout: full
title-block-banner: true
---


Archivo about.qmd

Contenido original de about.qmd

Así dejaremos el fichero about.qmd

  • Si en el yaml se activa la opción about: (linea 4), entonces puedes usar unas plantillas que Quarto tiene disponibles para crear About’s pages.

  • Como puedes ver aquí hay 5 plantillas: jolla, trestles, solana, marquee y broadside.

  • Aquí tienes la documentación oficial sobre estas plantillas.


Tarea 2.6: Modificar el contenido de about.qmd

  • Antes he dicho que solo modificaríamos la linea 5, pero mejor si lo complementamos con algunas acciones más, como el tamaño de la foto y su forma, por eso he añadido 2 lineas tras template:trestles.

  • Lógicamente estaría bien que sustituyeses la foto: se trata de cambiar profile.jpg, en la linea 3, por la ruta a tu foto.

  • Abajo tienes el código:

---
title: Yo mismo
image: profile.jpg
about:
  template: trestles    #- {jolla, solana, ...}
  image-width: 10em     #- https://cybmeta.com/em-y-rem
  image-shape: round    #- rectangle, round, rounded
  links:
    - icon: twitter
      text: Twitter
      href: https://twitter.com
    - icon: linkedin
      text: LinkedIn
      href: https://linkedin.com
    - icon: github
      text: Github
      href: https://github.com
---
        
Hola, soy "Yo mismo". 
      
Estoy asistiendo al taller **Mi primer blog con Quarto** impartido en el [I Congreso & XII Jornadas de Usuarios de R](http://r-es.org/12jr/){target="_blank"} celebradas en Córdoba (Spain), 23-25 de noviembre de 2022.
      
En un ratito ya piloto Quarto y genero my blog!!! 🙂


Archivo styles.css

  • Puedes cambiar la apariencia estética del blog usando los themes predefinidos en Quarto o puedes usar el archivo styles.css1

Tarea 2.7: Modificar styles.css

  • Simplemente sustituye el contenido original del fichero styles.css por el contenido del siguiente chunk:
/* css styles */


/* justificar el texto */ 
p, ul, ol {
  text-align: justify; }


Resumen (tutorial nº 2)

  • En esta tercera parte del taller hemos aprendido a mejorar/tunear un poco nuestro blog.

  • Hemos modificado 3 archivos:

    1. _quarto.yml: hemos modificado el título del blog y la estructura de la barra de navegación; concretamente hemos añadido una página nueva.

    2. index.qmd: construye la Home Page de nuestra web. La opción listing: hace que nuestra web es en realidad un blog.

    3. about.qmd: hemos utilizado las plantillas de Quarto para configurar nuestra About page.

  • Finalmente hemos modificado (mínimamente) el archivo styles.css.


  • Aquí puedes ver como quedaría el blog tras haber modificado _quarto.yml, index.qmd, about.qmd y styles.css.

Práctica (tutorial nº 2)

En esta sección dedicaremos un tiempo a la práctica libre para que adaptes el blog a tus necesidades y gustos. Por ejemplo puedes probar:


  1. Añadir una nueva página a la web (quarto.yml). Os doy una posibilidad en la siguiente slide


  1. Modificar la apariencia del blog (realmente del listado de posts) jugando con las opciones que nos proporciona Quarto (index.qmd). Gracias YAML inteligence!!


  1. Modificar la apariencia de la página About (about.qmd)

Práctica 2.1: añadir una página más a nuestra web (_quarto.yml)

Evidentemente puedes probar a añadir la página que quieras, pero te ofrezco la siguiente posibilidad:

  • Con las lineas 12 y siguientes crear una página más en nuestro blog. La página se llamará “Más cosas”. Además, esta página nueva tiene la particularidad de que cuando recreemos el blog se convertirá en un desplegable con acceso a varias páginas: “Docencia 2”, “Docencia 3” y “Docencia 4”.

  • Fíjate que he puesto la nueva página a la izquierda (left:)

  • Además, puedes probar distintas opciones de theme (linea 34) y de highlighting (linea 38)

  • También puedes cambiar el color del fondo de la barra de navegación (linea 8)

project:
  type: website

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)
    left: 
      - text: "Docencia"
        href: docencia.qmd
      - text: "Más cosas"
        menu:
          - text: "Docencia 2"
            href: docencia.qmd
          - text: "Docencia 3"
            href: docencia.qmd
          - text: "---"
          - text: "Docencia 4"
            href: docencia.qmd
    right:
      - 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>"
 

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

Práctica 2.2: Modificar la apariencia del blog (index.qmd)

  • Se trata de cambiar las opciones predefinidas de tu archivo index.qmd

  • Con ello podremos cambiar la apariencia del listado de posts

  • Para ello tienes que ir jugando con las opciones que nos ha proporcionado la plantilla de Quarto en el fichero index.qmd.

  • la YAML inteligence te ayudará!! (vamos el autocompletado en el YAML)

  • No uses las opciones llamadas custom

---
title: "Mi listado de posts"
description: |
  Estoy tratando de hacer mi blog
listing:
  contents: posts
  sort: "date desc"
  type: default        #- {default, table, grid, custom}
  categories: true
  sort-ui: false
  filter-ui: false
page-layout: full         #- {article, full, custom}
title-block-banner: true  #- {true, false}
---

`

Práctica 2.3: Modificar la página About (about.qmd)

  • Se trata de cambiar las opciones predefinidas de tu archivo about.qmd

  • Estaría bien que pusieses una foto tuya.

  • Poner los enlaces a tus redes sociales y email

  • Puedes adaptar el texto y dar algo de formato a la página.

---
title: Yo mismo
image: profile.jpg
about:
  template: trestles    #- {jolla, solana, ...}
  image-width: 10em     #- https://cybmeta.com/em-y-rem
  image-shape: round    #- rectangle, round, rounded
  links:
    - icon: twitter
      text: Twitter
      href: https://twitter.com
    - icon: linkedin
      text: LinkedIn
      href: https://linkedin.com
    - icon: github
      text: Github
      href: https://github.com
---
        
Hola, soy "Yo mismo". 
      
Estoy asistiendo al taller **Mi primer blog con Quarto** impartido en el [I Congreso & XII Jornadas de Usuarios de R](http://r-es.org/12jr/){target="_blank"} celebradas en Córdoba (Spain), 23-25 de noviembre de 2022.
      
En un ratito ya piloto Quarto y genero my blog!!! 🙂


3. Convertir el blog en web personal

(3ª parte del tutorial)

¿Qué haremos en este tutorial?

  • Convertir nuestro blog en una web personal.

  • Haremos que la “landing page” o Home de nuestra web no sea una página con el listado de posts, sino que sea una página en la que se reciba a los futuros visitantes de nuestra web

  • Para ello solo tendremos que cambiar el nombre de dos ficheros y referenciar uno de ellos en _quarto.yml.


Tarea 3.1: Renombrar el archivo index.qmd

  • Cambia el nombre del fichero index.qmd a blog.qmd

  • Ahora este archivo no está referenciado en _quarto.yml, por lo que no se mostraría si hacemos un rebuild1.

Tarea 3.2: Incluir blog.qmd en la web

  • Para que blog.qmd, la página que contiene el listado de posts, se muestre en nuestra web hay que refrenciarlo/incluirlo en _quarto.yml

  • Simplemente, tendríamos que modificar las lineas 8 y 9 que ahora están referenciando al fichero about.qmd. Por ejemplo podríamos dejar las lineas 8 y 9 como se ve abajo (a la derecha):

  • Para hacerlo, es mejor copiar el código de abajo y pegarlo en _quarto.yml
project:
  type: website

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)
    left: 
      - text: "Docencia"
        href: docencia.qmd
      - text: "Más cosas"
        menu:
          - text: "Docencia 2"
            href: docencia.qmd
          - text: "Docencia 3"
            href: docencia.qmd
          - text: "---"
          - text: "Docencia 4"
            href: docencia.qmd
    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>"
 

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
  • Aún no podemos refrescar la web porque ahora no tenemos archivo index.qmd.

:::

Tarea 3.3: Renombrar el archivo about.qmd

  • Cambia el nombre del fichero about.qmd a index.qmd, con lo que pasará ser nuestra “landing page”.

  • Como el antiguo fichero about contenía nuestra foto parece que es un buen candidato a ser nuestra “Home”

Tarea 3.4: Hacemos un rebuild de la web

  • Ahora ya tenemos fichero index.qmd, por lo que ya podemos hacer un rebuild de nuestra web y veremos la nueva estructura de nuestra web, con una foto nuestra en la “landing page”.

  • Para ello: Build > Render Website en RStudio.

4. Workflow: ¿cómo crear un post?

(4ª parte del tutorial)

¿Qué haremos en este tutorial?

  • Ver como podemos iniciar un nuevo post

  • (podemos marcar post todavía no acabados con draft: true en el yaml del post)


¿Donde están los posts del blog?

  • Los ficheros .qmd que generan los posts están en la carpeta posts (de nuestro Qproject que genera el blog).

  • Cada post está en una carpeta diferente1:

  • Veamos (en la siguiente slide) el contenido de ./posts/welcome/

Contenido de cada subcarpeta de ./posts/


  • Por ejemplo de ./posts/welcome/

Contenido de la carpeta welcome que genera el post titulado “Welcome to my blog”

Contenido del archivo index.qmd”


Tarea 4.1: Creando un nuevo post

  • Crea una nueva subcarpeta en ./posts/

  • Ponle nombre, por ejemplo: “my-primer-post”

  • Copia en la carpeta que hemos creado el contenido de la carpeta de uno de los 2 posts. Por ejemplo copia los 2 archivos que hay en ./posts/welcome/ y pégalos en ./posts/my-primer-post/; es decir, pegamos el archivo index.qmd y tumbnail.jpg en nuestra nueva carpeta.

  • Vuelve a regenerar el blog: Build > Render Website y verás que ahora nuestro blog ya tiene tres posts.

Tarea 4.2: Modificando el tercer post

  • Modifica el contenido de /.posts/my-primer-post/index.qmd. Por ejemplo, puedes dejarlo así:
---
title: "Mi primer post con Quarto"
author: "Pedro J. Pérez"
date: "2022-10-25"
categories: [R, quarto]
image: "thumbnail.jpg"
---

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

  • La opción de yaml (linea 6): image: "thumbnail.jpg" nos permite elegir la imagen que acompañara al post en la listing page.

  • Vuelve a regenerar el blog: Build > Render Website


Resumen (tutorial nº 4)

  • En esta cuarta parte del taller hemos visto como podemos generar/escribir nuevos posts para nuestro blog: solo hay replicar una de las carpetas de anteriores posts y cambiarle el nombre.


  • Hemos visto como cambiar la imagen que acompaña a los posts en la “listing page”.
  • Recuerda que podemos marcar un post con draft: true en el yaml del post.


  • En el siguiente tutorial veremos en profundidad las posibilidades que nos ofrece Quarto para escribir nuestros posts.


5. Escribiendo posts: practicando con Quarto

(5ª parte del tutorial)

¿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í.


Ficheros .qmd

  • Los ficheros .qmd tienen 3 partes: YAML, texto y chunks de código.

  • Veámoslas una a una

1. YAML

YAML: ideas importantes


  • El encabezamiento o YAML sirve para fijar opciones y metadatos de nuestro documento.


  • El YAML será procesado varias veces durante el procesado del documento: es leído por Quarto, knitr y Pandoc e influirá en el output final.


  • El hecho de estar trabajando dentro de un Qproject nos da mucha versatilidad a la hora de especificar el YAML de nuestros documentos .qmd. Documentación oficial aquí

El yaml de un post se puede especificar en 3 niveles


  1. Nivel proyecto:todo Qproject tiene archivo _quarto.yml. Todo documento que se procese dentro del proyecto, heredará los metadatos definidos en _quarto.yml.

  2. Nivel carpeta: si en una carpeta existe un documento _metadata.yml, los documentos de esa carpeta heredan sus metadatos. La carpeta ./posts/ de un blog suele tener un archivo _metadata.yml.

  3. Nivel documento: En el yaml del propio documento .qmd


  • Si hay conflictos prevalecen las opciones del nivel documento, luego nivel carpeta y finalmente nivel proyecto.

  • Documentación oficial de Quarto con las principales opciones que se pueden fijar en el YAML para documentos html: aquí y aquí

YAML: tal como lo tenemos ahora

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/

YAML: NIVEL PROYECTO (opciones en _quarto.yml)

En _quarto.yml se suelen poner opciones referentes a 3 aspectos:

# 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


  • linea 4: podemos elegir la carpeta de destino de nuestro blog
  • linea 5: podemos cambiar el render directory de los .qmd


Documentación oficial aquí.

#- 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:

  • lineas 28 a 37: se añade un pie de página al blog

  • lineas 24 y 25: Hemos añadido un elemento a la navbar concretamente el icono Home. La documentación oficial para elementos de navegación está aquí

  • linea 4: añadimos un favicon

  • lineas 5 y 6: el url de la web y del repo en Github

  • lineas 7-10: elementos de redes sociales. La documentación oficial para estos elementos esta aquí


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


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… Documentación oficial aquí y aquí

Un ejemplo “completito” de _quarto.yml

Si quieres ver un documento _quarto.yml completito, ve aquí. Pertenece a la web de Quarto.


project:
  type: website
  output-dir: _site
  resources:
    - "/docs/download/_download.json"
    - "/docs/download/_prerelease.json"
    - "/_redirects"

website:
  title: "Quarto"
  image: "quarto.png"
  favicon: "favicon.png"
  google-analytics: "G-FV9Z7SDZ0M"
  open-graph: true
  twitter-card: true
  site-url: https://quarto.org
  repo-url: https://github.com/quarto-dev/quarto-web
  repo-actions: [edit, issue]
  page-navigation: true
  search:
    algolia:
      index-name: prod_QUARTO
      application-id: ZPJB5I1QN7
      search-only-api-key: 41be6c1e0a7fea4a51b107810facf577
      analytics-events: true
      show-logo: true
  page-footer:
    left: |
      Proudly supported by
      [![](https://www.rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-flat.svg){fig-alt="RStudio" width=65px}](https://www.rstudio.com)
    center:
      - text: "About"
        href: about.qmd
      - text: "FAQ"
        href: docs/faq/index.qmd
      - text: "License"
        href: license.qmd
      - text: "Trademark"
        href: trademark.qmd
    right:
      - icon: twitter
        href: https://twitter.com/quarto_pub
        aria-label: Quarto Twitter
      - icon: github
        href: https://github.com/quarto-dev/quarto-cli
        aria-label: Quarto GitHub
  navbar:
    background: light
    logo: quarto.png
    logo-alt: "Quarto logo."
    title: false
    collapse-below: lg
    left:
      - text: "Overview"
        href: index.qmd
      - text: "Get Started"
        href: docs/get-started/index.qmd
      - text: "Guide"
        href: docs/guide/index.qmd
      - text: Extensions
        href: docs/extensions/index.qmd
      - text: "Reference"
        href: docs/reference/index.qmd
      - text: "Gallery"
        href: docs/gallery/index.qmd
      - text: "Blog"
        href: docs/blog/index.qmd
      - text: "Help"
        menu:
          - text: "Report a Bug"
            icon: "bug"
            href: "https://github.com/quarto-dev/quarto-cli/issues"
          - text: "Ask a Question"
            icon: "chat-right-text"
            href: "https://github.com/quarto-dev/quarto-cli/discussions"
          - text: "FAQ"
            icon: "question-circle"
            href: docs/faq/index.qmd
    right:
      - icon: twitter
        href: https://twitter.com/quarto_pub
        aria-label: Quarto Twitter
      - icon: github
        href: https://github.com/quarto-dev/quarto-cli
        aria-label: Quarto GitHub

  sidebar:
    - id: get-started
      title: "Get Started"
      style: "floating"
      collapse-level: 2
      align: left
      contents:
        - docs/get-started/index.qmd
        - text: "Tutorial: Hello, Quarto"
          href: docs/get-started/hello/
        - text: "Tutorial: Computations"
          href: docs/get-started/computations/
        - text: "Tutorial: Authoring"
          href: docs/get-started/authoring/

    - id: guide
      collapse-level: 1
      contents:
        - text: "Guide"
          href: docs/guide/index.qmd
        - section: "Authoring"
          contents:
            - docs/authoring/markdown-basics.qmd
            - docs/authoring/figures.qmd
            - docs/authoring/tables.qmd
            - docs/authoring/diagrams.qmd
            - docs/authoring/videos.qmd
            - docs/authoring/callouts.qmd
            - docs/authoring/article-layout.qmd
            - section: "Scholarly Writing"
              contents:
                - docs/authoring/title-blocks.qmd
                - docs/authoring/footnotes-and-citations.qmd
                - docs/authoring/cross-references.qmd
                - docs/authoring/create-citeable-articles.qmd
                - docs/authoring/appendices.qmd
        - section: "Computations"
          contents:
            - docs/computations/python.qmd
            - docs/computations/r.qmd
            - docs/computations/julia.qmd
            - docs/computations/ojs.qmd
            - docs/computations/execution-options.qmd
            - docs/computations/parameters.qmd
        - section: "Tools"
          contents:
            - docs/tools/jupyter-lab.qmd
            - docs/tools/rstudio.qmd
            - docs/tools/vscode.qmd
            - docs/tools/text-editors.qmd
            - section: "Visual Editor"
              contents:
                - text: Editor Basics
                  href: docs/visual-editor/index.qmd
                - docs/visual-editor/technical.qmd
                - docs/visual-editor/content.qmd
                - docs/visual-editor/options.qmd
                - docs/visual-editor/markdown.qmd
        - section: "Documents"
          contents:
            - section: "HTML"
              contents:
                - docs/output-formats/html-basics.qmd
                - docs/output-formats/html-code.qmd
                - docs/output-formats/html-themes.qmd
                - docs/output-formats/html-publishing.qmd
            - section: "PDF"
              contents:
                - docs/output-formats/pdf-basics.qmd
                - docs/output-formats/pdf-engine.qmd
            - section: "MS Word"
              contents:
                - docs/output-formats/ms-word.qmd
                - docs/output-formats/ms-word-templates.qmd
            - section: "Markdown"
              contents:
                - docs/output-formats/gfm.qmd
                - docs/output-formats/hugo.qmd
                - docs/output-formats/docusaurus.qmd
            - docs/output-formats/all-formats.qmd
        - section: "Presentations"
          contents:
            - text: "Overview"
              href: docs/presentations/index.qmd
            - section: docs/presentations/revealjs/index.qmd
              contents:
                - text: "Reveal Basics"
                  href: docs/presentations/revealjs/index.qmd
                - docs/presentations/revealjs/presenting.qmd
                - docs/presentations/revealjs/advanced.qmd
                - docs/presentations/revealjs/themes.qmd
            - docs/presentations/powerpoint.qmd
            - docs/presentations/beamer.qmd
        - section: "Websites"
          href: docs/websites/website-basics.qmd
          contents:
            - docs/websites/website-basics.qmd
            - docs/websites/website-navigation.qmd
            - docs/websites/website-blog.qmd
            - docs/websites/website-search.qmd
            - docs/websites/website-tools.qmd
            - docs/websites/website-about.qmd
            - section: "Listing Pages"
              href: docs/websites/website-listings.qmd
              contents:
                - docs/websites/website-listings.qmd
                - docs/websites/website-listings-custom.qmd
        - section: "Books"
          href: docs/books/book-basics.qmd
          contents:
            - docs/books/book-basics.qmd
            - docs/books/book-structure.qmd
            - docs/books/book-crossrefs.qmd
            - text: "Customizing Output"
              href: docs/books/book-output.qmd
        - section: "Interactivity"
          contents:
            - text: "Overview"
              href: docs/interactive/index.qmd
            - section: docs/interactive/ojs/index.qmd
              contents:
                - text: "Introduction"
                  href: docs/interactive/ojs/index.qmd
                - docs/interactive/ojs/libraries.qmd
                - docs/interactive/ojs/data-sources.qmd
                - docs/interactive/ojs/ojs-cells.qmd
                - docs/interactive/ojs/shiny.qmd
                - docs/interactive/ojs/code-reuse.qmd
                - section: "Examples"
                  contents:
                    - docs/interactive/ojs/examples/penguins.qmd
                    - docs/interactive/ojs/examples/sunburst.qmd
                    - docs/interactive/ojs/examples/arquero.qmd
                    - docs/interactive/ojs/examples/population.qmd
                    - docs/interactive/ojs/examples/noaa-co2.qmd
                    - docs/interactive/ojs/examples/github.qmd
                    - docs/interactive/ojs/examples/layout.qmd
                    - section: "Shiny"
                      contents:
                        - text: "K-Means"
                          href: https://jjallaire.shinyapps.io/kmeans-shiny-ojs/
                        - text: "Binning"
                          href: https://jjallaire.shinyapps.io/binning-shiny-ojs/
                        - text: "Data Binding"
                          href: https://jjallaire.shinyapps.io/data-shiny-ojs/
                        - text: "Covid Map"
                          href: https://jjallaire.shinyapps.io/covid19-bicartogram/
            - section: docs/interactive/shiny/index.qmd
              contents:
                - text: "Introduction"
                  href: docs/interactive/shiny/index.qmd
                - docs/interactive/shiny/running.qmd
                - docs/interactive/shiny/execution.qmd
                - docs/interactive/shiny/resources.qmd
                - section: "Examples"
                  contents:
                    - text: "Old Faithful"
                      href: https://jjallaire.shinyapps.io/shiny-old-faithful/
                    - text: "K-Means"
                      href: https://jjallaire.shinyapps.io/shiny-k-means/
                    - text: "Diamonds"
                      href: https://jjallaire.shinyapps.io/shiny-diamonds/
            - section: "Widgets"
              contents:
                - docs/interactive/widgets/jupyter.qmd
                - docs/interactive/widgets/htmlwidgets.qmd
            - docs/interactive/layout.qmd
        - section: "Publishing"
          contents:
            - docs/publishing/index.qmd
            - docs/publishing/quarto-pub.qmd
            - docs/publishing/github-pages.qmd
            - docs/publishing/rstudio-connect.qmd
            - docs/publishing/netlify.qmd
            - docs/publishing/other.qmd
            - text: "Publishing with CI"
              href: docs/publishing/ci.qmd
        - section: "Projects"
          contents:
            - docs/projects/quarto-projects.qmd
            - docs/projects/code-execution.qmd
            - docs/projects/profiles.qmd
            - docs/projects/environment.qmd
            - docs/projects/scripts.qmd
            - docs/projects/virtual-environments.qmd
        - section: "Advanced"
          contents:
            - docs/authoring/includes.qmd
            - docs/authoring/variables.qmd
            - docs/output-formats/page-layout.qmd
            - docs/authoring/language.qmd
            - docs/authoring/conditional.qmd
            - docs/extensions/nbfilter.qmd
    - id: extensions
      title: "Extensions"
      contents:
        - "---"
        - section: docs/extensions/index.qmd
          contents: 
            - text: "Shortcodes & Filters"
              href: docs/extensions/listing-filters.qmd
            - text: "Journal Articles"
              href: docs/extensions/listing-journals.qmd
            - text: "Custom Formats"
              href: docs/extensions/listing-formats.qmd
            - text: "Revealjs Extensions"
              href: docs/extensions/listing-revealjs.qmd
            - docs/extensions/managing.qmd
        - "---"
        - section: docs/extensions/creating.qmd
          contents:
            - text: "Overview"
              href: docs/extensions/creating.qmd
            - docs/extensions/lua.qmd
            - docs/extensions/lua-api.qmd
            - text: "Distribution"
              href: docs/extensions/distributing.qmd
            - "---"
            - text: "Shortcodes"
              href: docs/extensions/shortcodes.qmd
            - text: "Filters"
              href: docs/extensions/filters.qmd
            - section: "Journal Articles"
              href: docs/journals/formats.qmd
              contents:
                - docs/journals/formats.qmd
                - docs/journals/templates.qmd
                - docs/journals/authors.qmd
            - docs/extensions/formats.qmd
            - docs/extensions/revealjs.qmd
            - docs/extensions/project-types.qmd
            - docs/extensions/starter-templates.qmd

    - id: reference
      title: "Reference"
      contents:
        - text: "Reference"
          href: docs/reference/index.qmd
        - section: "Formats"
          contents:
            - text: "HTML"
              href: docs/reference/formats/html.qmd
            - text: "PDF"
              href: docs/reference/formats/pdf.qmd
            - text: "MS Word"
              href: docs/reference/formats/docx.qmd
            - text: "OpenOffice"
              href: docs/reference/formats/odt.qmd
            - text: "ePub"
              href: docs/reference/formats/epub.qmd
            - section: "Presentations"
              contents:
                - text: "Revealjs"
                  href: docs/reference/formats/presentations/revealjs.qmd
                - text: "PowerPoint"
                  href: docs/reference/formats/presentations/pptx.qmd
                - text: "Beamer"
                  href: docs/reference/formats/presentations/beamer.qmd
            - section: "Markdown"
              contents:
                - text: "GitHub"
                  href: docs/reference/formats/markdown/gfm.qmd
                - text: "CommonMark"
                  href: docs/reference/formats/markdown/commonmark.qmd
                - text: "Markua"
                  href: docs/reference/formats/markdown/markua.qmd
            - section: "Wikis"
              contents:
                - text: "MediaWiki"
                  href: docs/reference/formats/wiki/mediawiki.qmd
                - text: "DokuWiki"
                  href: docs/reference/formats/wiki/dokuwiki.qmd
                - text: "ZimWiki"
                  href: docs/reference/formats/wiki/zimwiki.qmd
                - text: "Jira Wiki"
                  href: docs/reference/formats/wiki/jira.qmd
                - text: "XWiki"
                  href: docs/reference/formats/wiki/xwiki.qmd
            - section: "More Formats"
              contents:
                - text: "JATS"
                  href: docs/reference/formats/jats.qmd
                - text: "Jupyter"
                  href: docs/reference/formats/ipynb.qmd
                - text: "ConTeXt"
                  href: docs/reference/formats/context.qmd
                - text: "RTF"
                  href: docs/reference/formats/rtf.qmd
                - text: "reST"
                  href: docs/reference/formats/rst.qmd
                - text: "AsciiDoc"
                  href: docs/reference/formats/asciidoc.qmd
                - text: "Org-Mode"
                  href: docs/reference/formats/org.qmd
                - text: "Muse"
                  href: docs/reference/formats/muse.qmd
                - text: "GNU TexInfo"
                  href: docs/reference/formats/texinfo.qmd
                - text: "Groff Man Page"
                  href: docs/reference/formats/man.qmd
                - text: "Groff Manuscript"
                  href: docs/reference/formats/ms.qmd
                - text: "Haddock markup"
                  href: docs/reference/formats/haddock.qmd
                - text: "OPML"
                  href: docs/reference/formats/opml.qmd
                - text: "Textile"
                  href: docs/reference/formats/textile.qmd
                - text: "DocBook"
                  href: docs/reference/formats/docbook.qmd
                - text: "InDesign"
                  href: docs/reference/formats/icml.qmd
                - text: "TEI Simple"
                  href: docs/reference/formats/tei.qmd
                - text: "FictionBook"
                  href: docs/reference/formats/fb2.qmd
        - section: "Code Cells"
          contents:
            - text: "Jupyter"
              href: docs/reference/cells/cells-jupyter.qmd
            - text: "Knitr"
              href: docs/reference/cells/cells-knitr.qmd
            - text: "Observable"
              href: docs/reference/cells/cells-ojs.qmd
        - section: "Projects"
          contents:
            - text: "Options"
              href: docs/reference/projects/options.qmd
            - text: "Websites"
              href: docs/reference/projects/websites.qmd
            - text: "Books"
              href: docs/reference/projects/books.qmd
        - section: "More"
          contents:
            - text: "Dates"
              href: docs/reference/dates.qmd
            - text: "Globs"
              href: docs/reference/globs.qmd
            - text: "Citations"
              href: docs/reference/metadata/citation.qmd

bibliography: references.bib

format:
  html:
    toc: true
    theme:
      light: [cosmo, theme.scss]
    code-copy: true
    code-overflow: wrap
    css: styles.css
    include-after-body: js.html

filters:
  - filters/tools-tabset.lua


freeze: true

editor: visual

profile:
  group: 
    - [rc, prerelease]

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

YAML nivel carpeta

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

YAML nivel carpeta


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

YAML: nivel documento


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

2. TEXTO (o narrativas)

Texto (o narrativas)

  • Se escribe (al igual que .Rmd) en markdown. Aquí la documentación oficial de Quarto.

  • Sintaxis básica de markdown

3. CHUNKS

CHUNKS

Comportamiento similar a los documentos .Rmd. La documentación oficial está aquí


Principales diferencias con .Rmd

  • En ficheros .qmd, las opciones de los chunks se pueden especificar globalmente en el YAML y a nivel individual en cada uno de los chunks.

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

CHUNKS

  • Las principales opciones son: echo, eval, warning, error, output e include. Aquí la documentación oficial.

  • echo: además de 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í.

  • 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:

  • Hay más opciones para los chunks. Por ejemplo:

    • hacer folding code con #| code-fold: true

    • si el código es muy largo, puedes usar #| code-overflow: wrap o scroll

    • puedes hacer que se muestren los números de linea con #| code-line-numbers: true

La documentación oficial la tienes aquí.

4. Elementos básicos para escribir

Elementos básicos para escribir


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. Más elementos para “escribir”

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.

Veamos algunos de estos elementos con un poco de detalle.



(Después lo recordaremos con una Práctica)

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 TOC1.

  • 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.


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.


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í


6. Tuneado del blog

(6ª parte del tutorial)

¿Qué haremos en este tutorial?

  • Ver distintas opciones para adaptar el blog a nuestras necesidades

  • En concreto veremos 3 formas de hacerlo: a través de opciones de Quarto en el yaml, con CSS y con SASS


Intro

  • Quarto viene preparado con diferentes Bootstrap themes del proyecto Bootswatch project que le dan a nuestro blog una apariencia profesional y cuidada.


  • Creo que es mejor comenzar con un blog sencillo usando las plantillas (o themes) que nos ofrece Quarto pero, si queremos modificar la apariencia de nuestro blog, podemos hacerlo de 3 formas:

    1. Utilizando las opciones disponibles en Quarto para el yaml

    2. Utilizando CSS

    3. Utilizando SASS

1. Utilizando opciones del YAML


  • En el tutorial nº 6 repasamos las distintas opciones que tenemos disponibles para poder cambiar a través de opciones en los YAML’s (recuerda los 3 niveles).

  • Aquí solo pondré la documentación relevante junta y destacaré algunas de las opciones disponibles.

Documentación oficial

(sobre opciones disponibles en los YAML’s)


  • Referentes al proyecto: aquí

  • Referentes a la estructura de la web: aquí y aquí

  • Referentes a la estética: aquí y aquí

  • Referentes a las Listing Pages: aquí

  • Referentes a las About Pages: aquí

Algunas opciones de YAML

Algunas opciones de YAML (lang)

  • Si te has fijado, los metadatos de los documentos aparecen en inglés.

  • Por ejemplo, pone “Author” en lugar de “Autor” o “Autora”.


Hagamos algunos cambios

  • Si quisiéramos cambiar específicamente la opción de autor, tendríamos que poner en el YAML:
language: 
  title-block-author-single: "Autora"

  • Podemos cambiar todas las opciones especificando en el YAML lang: es.

  • La documentación oficial está aquí y aquí todos los elementos que se pueden modificar. Y aquí los ficheros específicos para diferentes idiomas. Aquí el documento para el castellano.


  • Si quisieras usar tu propio documento tendrías que poner en el YAML: language: custom.yml (lógicamente el fichero custom.yml tendría que existir y estar en la ruta correcta).

  • ¿Probamos a hacerlo?

Otras opciones para tunear desde el YAML

  • TOC: es importante tenerlo a nuestro gusto. Aquí tienes las opciones que puedes ajustar con opciones en el yaml

  • Chunks: aquí tienes las opciones que puedes ajustar desde el YAML

  • Resizing de los thumbnails. Un gist para hacerlo.

  • Algunas opciones de tuneado que puedes implementar desde el YAML. Prueba a poner estas opciones en el archivo _quarto.yml. Nuestro blog empeorará bastante. Más opciones aquí.

fontcolor: green          #- color del texto
linkcolor: purple         #- color de los enlaces
monobackgroundcolor: red  #- color de los cuadros de resultados de evaluar código
fontsize: 0.6em           #- tamaño del texto (más pequeño de lo normal: 1)
linestretch: 2.3          #- tamaño entre las lineas (1.6 es lo "normal")

2. Utilizando CSS


  • La apariencia visual del blog puede cambiarse utilizando CSS.

  • Veamos un ejemplo con el siguiente post

3. Utilizando SASS

  • La documentación oficial aquí

  • Aquí la documentación oficial de Quarto sobre los Bootswatch Sass Theme Files.

  • Bootstrap define unas 1.400 variables con las que controlar fuentes, colores, etc … . Puedes verlas aquí

  • Aquí están los ficheros .scss de los 25 built-in Bootswatch themes.


Publicando el blog


Fin!!

  • Muchas gracias por la atención 🙂

  • Espero que el taller haya salido OK ✅

  • Si alguien motivado por el taller acaba haciéndose un blog, please que me avise (pedro.j.perez@uv.es) 📫


  • Big thanks to all the Posit/Quarto team !!!! 👏🏼👏🏼 🙌🏼


  • Bye 👋🏼 👋🏼 , nos vemos en las próximas Jornadas en …

https://go.uv.es/pjperez/primer.blog