Tuneado básico del blog con Quarto

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

Autor

Afiliación

Pedro J. Pérez

Universitat de València

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 segunda parte del taller vamos a mejorar/tunear un poco nuestro blog.

• Las anteriores secciones del taller son

  0. Intro: se presenta el taller

  1. Creación de un blog (básico) con Quarto: vimos como crear y alojar un blog básico con RStudio y Quarto.

---

¿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

1 Archivo _quarto.yml

En la figura siguiente, en el lado izquierdo puedes ver el contenido original del fichero _quarto.yml. Al final dejaremos este fichero como la figura de la derecha.

Contenido original de _quarto.yml

Así dejaremos el fichero _quarto.yml

1.1 _quarto.yml original

Gráfico 1: Contenido original de _quarto.yml

Como puedes ver arriba en la Figura 1, el fichero _quarto.yml original tiene 3 partes:

• La primera parte del fichero _quarto.yml (lineas 1 y 2) simplemente específica que el proyecto es para hacer una página web (type: website). Esta primera parte del fichero _quarto.yml no lo vamos a tocar, lo vamos a dejar igual. Sí, en realidad, un blog es una página web en la que la “Home page” o “landing page” es un poco especial, es un poco especial porque es una página con un listado de posts, PERO, en definitiva un blog es una página web.

• La segunda parte del fichero _quarto.yml (lineas 4 a 12) sirve para decidir la estructura de la página web (en nuestro caso del blog). Esta segunda parte tiene 2 secciones

  • title: “blog_prueba_00”: aquí podemos cambiar el título de nuestro blog

  • navbar: aquí podemos cambiar la estructura de la barra de navegación del blog. En el archivo original se especifica que los elementos/pestañas de navegación se situan a la derecha y que habrán 3 links o pestañas: About y 2 iconos que nos llevaran a Github y a Twitter

• En la tercera parte del fichero _quarto.yml se especifica el formato. Como toda página web el formato es html. Además se especifica un theme y un fichero .css que nos permitirán modificar el aspecto estético del blog.

1.2 _quarto.yml modificado

Por ejemplo, podemos modificar el fichero _quarto.yml hasta dejarlo como:

Gráfico 2: Dejaremos así el contenido de _quarto.yml

Como puedes ver arriba en la Figura 2, al compararla con la Figura 1, hemos modificado el fichero _quarto.yml. Concretamente:

• La primera parte del fichero _quarto.yml (lineas 1 y 2) la hemos dejado igual. Seguimos queriendo hacer una web/blog.

• La segunda parte del fichero _quarto.yml (ahora lineas 4 a 19) si la hemos modificado:

  • Hemos cambiado el título del blog, ahora title: "Mi blog (aún en pruebas)". Está en la linea 5.

  • En la navbar (lineas 6 a 19): hemos cambiado la estructura de la barra de navegación del blog. Hemos hecho 3 cosas:

    1. Hemos añadido un logo a la barra de navegación con logo: profile.jpg (linea 7).

    2. En la parte derecha de la barra de navegación hemos añadido un icono para el email (icon:envelope) y hemos modificado el texto que se muestra en la pestaña about, esto último lo hemos hecho con text: "About me" en las lineas 9 y 10.

    3. Finalmente, hemos añadido una pestaña nueva (lineas 18 y 19) pero está vez a la izquierda de la barra de navegación: left: (linea 17). Fijate que esta nueva pestaña llamada “Docencia” creada con- text: "Docencia" (linea 18), esta referenciando a un archivo que no existe (aún) en el Qproject, está referenciando con href: docencia.qmd (linea 19) al archivo docencia.qmd. Lógicamente tendremos que crear este archivo.

• En la tercera parte del fichero _quarto.yml hemos cambiado el theme: minty y hemos añadido las lineas 25 toc: true que creará índices en las páginas de la web/blog¹, mientras que con highlight-style: a11y se cambia el formato visual de los chunks de código que hayan en la página web.

Tarea 2.1

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

1.3 Crear docencia.qmd

• En el nuevo archivo quarto.yml(linea 19) se hace referencia al archivo docencia.qmd, así que tendremos que crearlo. Para ello:

Tarea 2.2

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

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

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.

• Aquí puedes ver como quedaría el blog tras haber modificado _quarto.yml. Como ves, tal como hemos dicho, hemos modificado las pestañas de la barra de navegación (por ejemplo ahora tenemos la pestaña Docencia a la derecha de la barra de navegación) y la apariencia (theme) del blog ha cambiado (recuerda theme: minty): ahora el color de la barra es verdecito.

• La verdad es que la barra de navegación en verde no me gusta mucho!! Enseguida dejaremos tiempo para que lo adaptes a tus gustos: será en la última sección de este tutorial.

2 Archivo index.qmd

En la figura siguiente, en el lado izquierdo puedes ver el contenido original del fichero index.qmd. Al final dejaremos este fichero como la figura de la derecha. Como verás, de momento, solo vamos a hacer cambios en la segunda linea: cambiaremos el título.

Contenido original de index.qmd

Así dejaremos el fichero index.qmd

• Como ves, index.qmd es un fichero (nuestra “Home Page”) sin contenido aparente: aparte del yamlno hay nada más. Sin embargo, justamente en el yaml se especifica, con la opción listing: (linea 3), que la página va a ser un listado; concrétamente un listado del contenido que haya en la carpeta posts; o sea, un listado con los posts que haya en la carpeta posts.

• Sí, con el trozo contents: posts (linea 4), se está especificando la carpeta donde estará alojado el contenido de los posts. Si miras la carpeta posts verás 2 subcarpetas, una para cada uno de los 2 posts del blog.

• Ya hablaremos de las subcarpetas donde está el contenido de los posts más adelante, pero adelanto que en cada carpeta hay un archivo index.qmd con el contenido de cada post.

Tarea 2.5

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

3 Archivo about.qmd

• Vamos a modificar mínimamente el fichero about.qmd. En la figura siguiente, en el lado izquierdo puedes ver el contenido original del fichero y en la derecha como lo dejaremos. Como verás solo vamos a hacer cambios en la quinta linea: cambios la plantilla predefinida.

Contenido original de about.qmd

Así dejaremos el fichero about.qmd

Tarea 2.6

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!!! 🙂

• Como has visto, si en el yaml se activa la opción about: (linea 3), entonces Quarto tiene disponibles unas plantillas para crear About’s pages. Aquí tienes la documentación oficial sobre estas plantillas. Como puedes ver aquí hay 5 plantillas: jolla, trestles, solana, marquee y broadside.

4 Archivo styles.css

• Puedes cambiar la apariencia estética del blog y dejarlo a tu gusto usando los themes predefinidos en Quarto o puedes usar el archivo styles.css²

• De momento, el archivo styles.css está vacío³

• El tuneado del blog con .css lo veremos con algo más de detalle en el tutorial nº 6, ahora mismo solo haremos unas modificaciones mínimas: voy a justificar el texto⁴.

Tarea 2.7

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; }       

• Acuérdate que para ver los cambios has de volver a generar el blog: Build > Render Website,

5 Resumen

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.

6 Práctica

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:

• Añadir una nueva página a la web (quarto.yml)

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

• Modificar la apariencia del blog jugando con las opciones que nos proporciona Quarto (index.qmd)

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}
---

`

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

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!!! 🙂

Notas

1. La opción toc: true creará un indice (o toc) en las páginas en las que hayan títulos de primer(#), segundo(##) o tercer nivel(###).

2. Veremos en el tutorial nº 6 que también podremos usar archivos .scss

3. En realidad no está vacío, pero solo tiene un comentario.

4. Esta es una modificación que tiene muchas criticas, pero, que se le va a hacer, a mi me gusta el texto justificado.

Reutilizar

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