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í.
¿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í.
Será un blog básico pero completamente operativo. Ya tendremos tiempo de mejorarlo, o tunearlo, en las siguientes secciones del taller.
Hay 3 formas de seguir el tutorial
La forma recomendada: utilizando Quarto a través de RStudio
Utilizar Quarto desde la Terminal y usar tu editor favorito (VScode …)
Utilizar RStudio Cloud
1 Creación de la carpeta (o Qproject) que contendrá nuestro blog
El primer paso para crear nuestro blog es crear el proyecto (o carpeta) donde se alojarán los ficheros que necesitemos para nuestro blog.
Vamos a crear el blog con Quarto pero interactuando con él a través de RStudio. Desde RStudio crearemos un Quarto Project1, concretamente un Quarto project prediseñado para crear blogs.
Tarea 1.1
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.
De momento aún no tenemos el blog, solo hemos creado una carpeta/Qproject pero, ya tenemos, dentro de la carpeta, la estructura de carpetas y archivos necesarios para crearlo.
Cuando creemos el blog, será un blog sencillito, vamos con lo mínimo, pero un blog.
Antes de crear el blog hagamos un pequeño repaso al contenido del Qproject, veamos su estructura de carpetas y archivos.
2 Contenido del Qproject
El Qproject que acabamos de crear y que permitirá crear el blog tiene esta estructura de archivos y carpetas:
Como ves en la figura anterior, el Qproject contiene 6 archivos y una subcarpeta. Voy a dividirlos en dos categorías:
los que no son importantes (al menos ahora mismo)
Los que sí son importantes ahora mismo, serán 3 archivos
2.1 Archivos “no importantes”
El archivo blog_prueba_00.Rproj
No es un archivo importante para el blog. Este archivo simplemente permite que RStudio reconozca la carpeta blog_prueba_00 como un Qproject.
El archivo styles.css
Sí será un archivo importante, pero lo veremos más adelante. Este archivo permitirá mediante CSS cambiar la estética de nuestro blog.
El archivo profile.jpg
Es sencillamente una foto. La tendremos que sustituir por una foto nuestra en la que estemos guapetes.
La carpeta posts
Será muy importante, pero la veremos más adelante. Esta carpeta es la que contendrá los posts que vayamos escribiendo.
Extensiones: el contenido de la carpeta /posts/
En la carpeta /posts/ hay un archivo de configuración (_metadata.yml) y una subcarpeta para cada post. Ahora mismo nuestro blog solo tiene 2 posts. La carpeta de cada post es similar: tiene 2 archivos que veremos más adelante.
2.2 Archivos sí importantes
Nos quedan 3 archivos que será en los que nos concentraremos en este tutorial:
_quarto_yml
Es el archivo que especifica como será la estructura y apariencia de nuestro blog.
about.qmd
Un archivo .qmd que generará el archivo about.html y que será una de las páginas de nuestro blog; precisamente en esta página se verá nuestra foto.
index.qmd
Otro archivo .qmd que generará el archivo index.html y que será la “landing page” o Home de nuestro blog.
3 Creación del blog
El Qproject que hemos creado tiene todo lo necesario para crear un blog, pero aún no lo hemos creado. Para crearlo solo tienes que:
Tarea 1.2
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.
Si todo ha ido bien, verás algo como esto en RStudio:
Puedes ver aquí, como quedaría el blog una vez alojado en internet.
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
Tras haber creado el blog, la estructura de carpetas de nuestro Qproject ha cambiado, concretamente se han generado 2 subcarpetas. Veámoslo:
Se han creado 2 subcarpetas
Si comparamos la estructura de carpetas antes y después de hacer Render Website vemos que se han creado 2 carpetas:
_freeze
La carpeta _freeze podemos dejarla para más adelante.
_site
La carpeta _site es la que realmente contiene el blog. Si alojas el contenido de esa carpeta en un servidor web se verá el blog que hemos creado.
Contenido de /_site/
Antes de publicar el blog, vamos a ver el contenido de la carpeta _site que es la que contiene realmente el blog:
Gráfico 2: Contenido de _site, la carpeta que contiene el blog
Tarea 1.3
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
La página principal del blog
Hemos visto que la página principal (Home) del blog consiste en una lista de los posts de nuestro blog2
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.
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
5 Alojando el blog
El blog que hemos creado no es muy interesante, pero vamos a ver lo fácil que es publicarlo en internet.
Hay muchas formas de alojar nuestro blog, por ejemplo Github PagesNetlify etc… , pero, de momento, usaremos el servicio Quartopub
Tarea 1.4
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.
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.
6 Resumen
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
Notas
Trabajar con Quarto projects tiene algunas ventajas, puedes verlas aquí↩︎
Ahora mismo es una lista corta porque el blog solo tiene 2 posts↩︎