Mi primer blog con Quarto - Tuneado del blog

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 sexta parte del taller veremos con un poco más de detalle como “mejorar” la apariencia de nuestro blog.
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.
5. Escribiendo posts: prácticando con Quarto. Vimos diversos elementos como div, call-outs etc… disponibles en Quarto para escribir posts.

¿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

1 Intro

Quarto viene preparado con diferentes Bootstrap themes del proyecto Bootswatch project que le dan a nuestro blog una apariencia profesional y cuidada; pero claro, todos los blogs hechos con Quarto tendrán una a apariencia similar. ¿Cómo podemos tunear/modificar un poco la apariencia de nuestro blog?

En este tutorial trataremos de dar 3 posibilidades, aunque la verdad es que creo que es mejor comenzar con un blog sencillo usando las plantillas (o themes) que nos ofrece Quarto. Si aún así nos empeñamos en modificar la apariencia de nuestro blog, podemos hacerlo de 3 formas:

utilizando las opciones disponibles en Quarto para el yaml
utilizando CSS
utilizando SASS

2 Opciones `YAML`

En esta sección repasaremos las opciones disponibles como opciones de yaml. Además recuerda que hay tres “niveles” de yaml:

2.1 Nivel proyecto: en el archivo _quarto.yml

2.2 Nivel carpeta: en el archivo _metadata.yml

2.3 Nivel documento (o post): en el yaml del propio documento .qmd

2.1 Nivel proyecto

En el archivo _quarto.yml hay 3 bloques:

Opciones referentes al proyecto
Opciones referentes a la estructura de la web y barra de navegación
Opciones digamos más “estéticas”

Abajo puedes ver las opciones más comunes referentes al proyecto. Yo suelo alojar las webs en el directorio docs, porque es el que se suele usar en Github Pages, así que sí suelo usar la linea 6.

# 1/ Opciones referentes al proyecto ----------------------------
#- QUARTO PROJECTS: https://quarto.org/docs/projects/quarto-projects.html

project:
  type: website
  output-dir: docs        #- carpeta donde se redirige el output (.html)
  # execute-dir: project  #- render directory: https://quarto.org/docs/projects/code-execution.html#working-dir
  # resources:
  #   - "/docs/download/_download.json"

Por supuesto que hay más opciones, puedes verlas aquí.

Está parte del archivo _quarto.yml sirve para crear la estructura de la página web: barra de navegación y sus pestañas, footer y sidebar. Yo no suelo utilizar sidebar porque no hago web’s complejas y me gusta más que la barra de navegación esté arriba y no en un lateral.

Abajo tienes diferentes opciones para crear la estructura de tu web¹:

#- PAGINAS WEB: https://quarto.org/docs/websites/ --------------------------------------

#- 2/ Opciones referentes a la estructura de la web -----------------
#- Web navigation: https://quarto.org/docs/websites/website-navigation.html

website:
  title: "Mi blog (aún en pruebas)"
  favicon: profile.jpg
  reader-mode: true  
  # site-url: https://....
  # repo-url: https://....
  # repo-actions: [edit, issue]
  search:   #- https://quarto.org/docs/websites/website-search.html
    location: navbar #- {navbar, sidebar}
    type: overlay   #- {overlay, textbox}
    copy-button: true
  open-graph: true #-https://quarto.org/docs/websites/website-tools.html#twitter-cards
  
  twitter-card:
    creator: "@tu-usuario-twitter"
    card-style: summary_large_image
  body-header: | 
    This page brought to you by <https://example.com>
  margin-header: |
    ![Logo image](/img/logo.png)
  # page-navigation: true

  navbar:
    logo: "profile.jpg"
    #pinned: true
    #background: "primary"    #- {“primary”, “secondary”, “success”, “danger”, “warning”, “info”, “light”, “dark”, or hex color} (el backgroung de la navbar)
    #foreground: "warning"    #- color navigation elements, text and links that appear in the navbar.
    #title: false
    #collapse-below: lg
    #pinned: true
    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:
    border: true
    background: light
    left: "© 2022 Pedro J. Pérez"
    #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: "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"

Por supuesto que hay más opciones, puedes verlas aquí y aquí.

Opciones referentes a diversos aspectos pero, en general, referentes a la estética (o theme) de la web. Documentación aquí y aquí.

Están son las opciones que he recopilado:

#- 3/ Opciones referentes al formato de salida  ---------------------
#- HTML basics: https://quarto.org/docs/output-formats/html-basics.html
#- HTML options: https://quarto.org/docs/reference/formats/html.html

format:
  html:
    #- https://quarto.org/docs/output-formats/html-themes.html
    #theme:
    #  light: [flatly, theme.scss]  
    css: styles.css
    toc: true
    #- https://quarto.org/docs/output-formats/html-code.html#highlighting
    highlight-style: a11y
    code-copy: true
    code-overflow: wrap
    #include-after-body: js.html
    theme:
      light: flatly
      dark: [darkly, theme-dark.scss]

#- 4/ Más opciones  ----------------------------------------------------
bibliography: references.bib
filters:
  - filters/tools-tabset.lua
freeze: true
editor: visual

description: "Un blog para aprender y divertirme" #- necesario para RSS

2.2 Nivel carpeta

En realidad, las opciones que se pongan en el archivo _metadata.ym podrían perfectamente ir en _quarto.yml pero, el hecho de poder hacerlo indistintamente en ambos nos da más flexibilidad a la hora de hacer pequeñas adaptaciones de estilo para los archivos .qmd de una determinada carpeta.

Estas son las opciones que he recopilado. Muchas de ellas (o todas) podrían ir perfectamente en el yaml del propio documento o incluso en el fichero _quarto.yml, pero al situarlas en el archivo _metadata.yml afectarán a todos los posts pero solo a los posts.

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

# freeze computational output
# (see https://quarto.org/docs/projects/code-execution.html#freeze)
freeze: true


# Enable banner style title blocks: https://quarto.org/docs/authoring/title-blocks.html
title-block-banner: true      #- imagenes/economia.gif
#title-block-style: default   #- {none, plain, default}
#title-block-banner-color : "#FFDDFF"



# Enable CC licence appendix
license: "CC BY"

# Default for table of contents
toc: true
toc-title: Índice
toc-location: left


# Default knitr options
execute:
  echo: true
  message: false
  warning: false
  eval: true

# Default author
author:
  - name: Pedro J. Pérez
    #url: https://djnavarro.net
    affiliation: Universitat de València
    affiliation-url: https://www.uv.es
    orcid: 0000-0001-9375-6330

# Default fields for citation
citation: true

# image as thumbnail
# image: "imagenes/thumbnail.png"

#- https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/posts/16-code-tools/
code-fold: true
code-tools: true
code-link: true

#- https://quarto.org/docs/authoring/cross-references.html#options
crossref:
  fig-title: Gráfico   # (default is "Figure")
  tbl-title: Tabla     # (default is "Table")
  #title-delim: —      # (default is ":")

2.3 Nivel documento

En el yaml del propio documento que genera un post se pueden introducir la mayoría de opciones de yaml pero parece lógico que los posts de un blog compartan estilo y, por tanto, las principales opciones del yaml creo que es mejor establcerlas a nivel de carpeta en metadata.yml. De esta forma, en el yaml del propio documento quedarían opciones como el título del post, categorías, fecha e imagen.

#- YAML de un post ------------------------------
---
title: "Mi primer post con Quarto"
author: "Pedro J. Pérez"
date: 2022-10-25
date-format: short
categories: [R, quarto]
image: "thumbnail.jpg"
---

3 `YAML` por categoría

Ahora mostraré opciones que podemos utilizar en el YAML para diferentes cuestiones:

#- formato de salida ---------------------------
format:
  html:
    #- https://quarto.org/docs/output-formats/html-themes.html
    #theme:
    #  light: [flatly, theme.scss]  
    css: styles.css
    toc: true
    #- https://quarto.org/docs/output-formats/html-code.html#highlighting
    highlight-style: a11y
    code-copy: true
    code-overflow: wrap
    #include-after-body: js.html
    theme:
      light: flatly
      dark: [darkly, theme-dark.scss]
    linkcolor: "red"
    monobackgroundcolor: "green" #- color de los cuadros de resultados de evaluar código
    fontsize: 0.8em
    linestretch: 1.3
    
#- opciones para TOC ---------------------------
toc: true
toc-title: Índice
toc-location: left

# author ---------------------------------------
author:
  - name: Pedro J. Pérez
    #url: https://
    affiliation: Universitat de València
    affiliation-url: https://www.uv.es
    orcid: 0000-0001-9375-6330

# opciones para chunks --------------------------
# https://quarto.org/docs/computations/execution-options.html#output-options
execute:
  echo: true    #- {true, false, fenced}
  message: false
  warning: false
  eval: true


#- opciones knitr ---------------------------------
#- https://yihui.org/knitr/options/
knitr:
  opts_chunk: 
    collapse: true
    comment: "#>" 
    R.options:
      knitr.graphics.auto_pdf: true

4 Listing pages

#- LISTING page -----------------------------

---
title: "Mi listado de post"
description: |
  Un blog para aprender y divertirme #- necesario para RSS (https://quarto.org/docs/websites/website-listings.html#feeds)
listing:
  contents: posts
  #- listing options: https://quarto.org/docs/websites/website-listings.html#listing-options
  #- https://quarto.org/docs/websites/website-listings.html#sorting-items
  sort: "date desc"
  #-  https://quarto.org/docs/websites/website-listings.html#listing-types
  type: default  #- {default, table, grid, custom}
  categories: true
  feed: false
  sort-ui: false
  filter-ui: false
  fields: [image, date, title, description, categories, author, reading-time, file-modified]
  field-display-names:
    # title: "Report"
    date_format: medium
  image: imagenes/thumbnail.jpg
  image-align: left
page-layout: full         #- {article, full, custom}
# 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-block-banner: true  #- #- {true, false, "#FFDDFF",  "image.jpg"}
title-block-style: default #- {default, plain, none}
title-block-banner-color: red  #- {black, "#FFDDFF"} color del texto dentro del banner
feed: true   #- RSS: https://quarto.org/docs/websites/website-listings.html#feeds
---

La documentación oficial está aquí

5 About pages

#- About page ---------------------------------
#- Pages: https://quarto.org/docs/websites/website-about.html
---
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
    - icon: envelope
      text: email
      url: "mailto:<tu-mail@uv.es>"
---

La documentación oficial para las About Pages está aquí

6 CSS

La apariencia visual del blog puede cambiarse utilizando CSS. El objetivo no es crear un tutorial sobre CSS, de hecho mis conocimientos de CSS son limitados, sino solo mostrar con un ejemplo cómo poder incorporar algunos cambios en nuestro blog mediante el uso de CSS. Para ello he elaborado el siguiente post

Algunos recursos relacionados con CSS/html:

Slidecraft 101: Code and Output
Slidecraft 101: Colors and Fonts
Business Reports with R Markdown: How to better theme report?
Internet is hard
[CSS basics] (https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/CSS_basics) y Html basics de Mozilla.
Vídeo HTML Crash Course For Absolute Beginners
CSS tricks y Codepen
Learn to Code HTML & CSS
Bootstrap CSS grid para layout’s complejos

7 SASS

Recordar que muchos de los cambios que podemos hacer con SASS, con archivos .scss, también pueden hacerse desde los distintos YAML’s de nuestro blog, esta fantástica slide nos sirve de ejemplo.

La documentación oficial de Quarto para documentos html sobre como usar los themes y tunearlos con Sass; además podemos encontrar un listado de variables Sass y un archivo .scss donde ver todas las variables Sass usadas en los themes. Aquí puedes ver los ficheros .scss usados por los 25 built-in Bootswatch themes. Aquí hay más información sobre el uso de Sass en Quarto. Para saber aún más, la web de Quarto nos redirige aquí.

Para las slides en formato revealjs: la documentación oficial de Quarto sobre como usar los themes y tunearlos con Sass; además podemos encontrar un listado con las variables Sass y un listado de archivos .scss para revealjs slides.

Algunas referencias sobre SASS:

Customizing Quarto Websites: Make your website stand out using SASS: unas slides de Sam Csik.
Video tutorial de Albert Rapp. llegué a él gracias a este post.
En este post de 2021 se anunciaba que se podía utilizar SASS en el entorno Rmarkdown gracias al paquete sass y en su web se puede encontrar esta vignette.

7.1 “Práctica”

Sencillamente, para ver cómo es un archivo .scss vamos a ir al blog de Danielle Navarro y desde allí podemos dirigirnos al repo del blog donde podemos ver su archivo ember.scss. No es un archivo muy largo, simplemente coge el theme “litera” como base y ajusta un par de cosas como las fuentes.

Si quisiéramos copiar/usar los ajustes de Danielle, sólo tendríamos que copiar su archivo en la carpeta raíz de nuestro blog y añadir en _quarto.yml la siguiente linea anidada en format: html:. Algo como esto:

format:
  html:
    theme: ember.scss

Notas

Son las opciones que he ido recopilando y que me han parecido que pueden llegar a serme útiles algún día, por eso las recopilo, para tenerlas a mano↩︎

Reutilizar

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

1 Intro

2 Opciones YAML

2.1 Nivel proyecto

2.2 Nivel carpeta

2.3 Nivel documento

3 YAML por categoría

4 Listing pages

5 About pages

6 CSS

7 SASS

7.1 “Práctica”

Notas

Reutilizar

2 Opciones `YAML`

3 `YAML` por categoría