Guía de creación de un blog con Quarto

Expliquemos de la manera más sencilla posible el proceso que he seguido para crear este blog con Quarto y subirlo a Codeberg.

Considere el lector que hasta hace relativamente poco tiempo no tenía idea de git ni de Quarto, por lo que el proceso no debería resultar especialmente complicado para un usuario que haya hecho sus pinitos con una terminal. Por supuesto, mis instrucciones serán para linux, así que el usuario de otro S.O. tendrá que adaptarla en consecuencia (ver instrucciones de instalación de git).

Crear repositorio

El primer paso es crear un repositorio para los archivos de configuración del blog y otro repositorio denominado pages donde subiremos el contenido de la carpeta _site generada por Quarto para ver el blog en la dirección

{usuario}.codeberg.pages.

Veremos que alternativamente se puede utiizar un único repositorio, aunque siempre será conveniente tener una web principal en pages

Crear blog

Después de instalar Quarto vamos a la terminal y, desde la ruta que consideremos apropiada, creamos la base del blog

quarto create-project {nombre_proyecto} --type website:blog

En mi caso

quarto create-project blog --type website:blog

Esto nos creará el sistema básico de archivos con dos posts de ejemplo

Básicamente, las paǵinas editables en Markdown (index.qmd y about.qmd), un archivo de configuración (_quarto.yml), y una hoja de estilos. Cada post también tendrá su archivo md editable index.qmd.

Podemos ver el aspecto inicial del blog con

quarto preview blog

código que genera un localhost para ver la web en el navegador, creando para ello una carpeta _site con los archivos html que serán la versión final del blog visualizable en el navegador. Lo bonito del caso es que, editando cualquiera de los archivos, la versión web se actualiza una vez guardamos los cambios de edición.¹

Configuración básica del blog

Vayamos ahora con la configuración básica del blog en el archivo _quarto.yml , que en mi caso ha quedado como sigue

project:
  type: website

website:
  title: "Blog"
  site-url: https://pedroj.codeberg.page/blog/
  description: "Nuevo blog personal de @ecosdelfuturo@mstdn.social"
  navbar:
    right:
      - about.qmd
      - icon: wordpress
        href: https://xclima.wordpress.com/
      - icon: mastodon
        href: https://mstdn.social/@ecosdelfuturo
      - icon: code-square
        href: https://codeberg.org/pedroj
      - icon: rss
        href: index.xml
format:
  html:
    theme: cosmo
    css: styles.css
comments:
  hypothesis: true

La mayoría de los cambios son sólo personalización de lo que ya viene por defecto, destacando los iconos de redes sociales, la elección del tema, y dos cosas importantes que sí que no vienen por defecto: el feed y los comentarios.

Quarto ofrece tres formas de añadir la posibilidad de comentarios. Dos de ellas están basadas en aplicaciones disponibles en Github pero no en Codeberg, por lo que sólo me quedaba la tercera, Hypothesis, una plataforma open-source de anotaciones y comentarios en la web que me ha gustado bastante, muy en la línea de la filosofía de utilizar open-source comunitario.

Activarla es tan sencillo como añadir

comments:
  hypothesis: true

Para añadir un feed lo hacemos en el archivo index.qmd principal del blog, añadiendo la línea que vemos en la imagen.

Si además queremos poner un icono de feed en la barra de navegación del blog, añadimos al archivo _quarto.yml otro icono apuntando a la dirección del feed generado index.xml

- icon: rss
        href: index.xml

Subir proyecto al repositorio remoto

Ahora toca subir todos los archivos a Codeberg. Para ello utilizaremos git.² El propio repositorio nos propone la manera de hacerlo. En una terminal, dentro de la carpeta del proyecto hacemos

git init #iniciamos repositorio
git checkout -b main #nos aseguramos trabajar en la rama principal
git add --all #Añadimos todos los archivos para seguimiento
git commit -m "first commit" #Realizamos una instantánea (commit)
git remote add origin https://codeberg.org/usuario/repo.git #Añadimos repositorio remoto
git push -u origin main #Subimos el proyecto local al repositorio

Al hacer push, git nos pedirá las credenciales de acceso a nuestra cuenta en Codeberg.³

Publicar el blog

En el paso anterior hemos subido todos los archivos del proyecto al repositorio remoto. Pero ahora nos interesa que los archivos html de la carpeta _site, que generamos cada vez que hacemos una previsualización con

quarto render --html

Puedan servirse desde codeberg como web. Esto no es tan simple de hacer correctamente, pero veremos primero una manera sencilla (aunque poco recomendable) que puede servir a quien no quiera lidiar con git en mayor profundidad.

Servir el blog (método sencillo no recomendado)

Creamos un nuevo repositorio denominados pages. Codeberg servirá una web alojada en ese repositorio pages en la dirección usario.codeberg.page

Generamos la carpeta _site de nuestro blog con

quarto render --html

Hacemos una copia de la carpeta _site fuera de la carpeta del proyecto. En dicha copia inciamos un nuevo repositorio local y lo subimos al nuevo repositorio remoto con los mismos comando de git vistos anteriormente.

El problema con este procedimiento es que en un segundo push que hagamos después de modificar nuestro blog tendremos que tener mucho cuidado en no eliminar el archivo .gitde configuración en la carpeta destino de nuestra copia de _site, algo que resulta muy engorroso si uno publica con frecuencia.

En un segundo push sólo tendríamos que hacer

git add --all
git commit -m "second commint"
git push -u origin main

Servir el blog (método más complejo recomendado)

Codeberg tambien puede servir un blog/web desde la carpeta de un repositorio que contenga los archivos html necesarios siempre que estén asignados a la rama pages. Por ejemplo, los archivos de nuestro repositorio con el nombre blog los serviría en este caso en la dirección usario.codeberg.page/blog Así, ya no necesitaremos el repositorio pages y podemos hacer todo desde el mismo repositorio blog

Actualizaremos así nuestros archivos del proyecto al respositorio con git tal y como hicimos anteriormente, pero ahora repetiremos el siguiente procedimiento con la carpeta sites generada creando una nueva rama pages

quarto render --html #generamos el blog en la carpeta _sites

git clone https://codeberg.org/usuario/blog.git pages.git #clonamos el repositorio remoto en la carpeta temporal ``pages.git``

rm -r pages.git/* #Borramos todos los archivos de la carpeta respetando la configuración de git

rsync -av _site/* pages.git/ #Sincronizamos la carpeta ``_site`` generada con la temporal ``pages.git``

cd pages.git #Nos situamos en la carpeta temporal

git checkout --orphan current #Nos lleva a una rama huéfana de commints dejando intacta la rama main

git add -A #Añadimos todo los archivos al nuevo commint

git commit -m "Deployment at $(date)"

git branch -m pages # Cambiamos(creamos) la rama _pages_

git push -f origin pages

cd .. 

rm -rf pages.git #borramos la carpeta temporal

Cada vez que actualicemos algún archivo del blog, tendremos que volver a repetir todo esto teniendo cuidado con lo errores. Por supuesto, este procedimiento puede automatizarse con un script.

Formatos locales de post

Este post empieza con el siguente yaml de configuración situado al principio del archivo md del post

title: "Guía de creación de un blog con Quarto"
author: "Pedro J."
date: '2022-12-08'
date-modified: last-modified
categories: [DIY]
footnotes-hover: true
code-tools: true
toc: true
toc-title: Contenidos
toc-depth: 3
toc-expand: 3
highlight-style: dracula
filters:
  - mastodon-comments
mastodon_comments:
  user: "ecosdelfuturo"
  host: "mstdn.social"
  toot_id: "113772827104158153"

Sobre el estándar que genera quarto he añadido: - Fecha de edición modificada

Notas al pie emergentes
Icono de acceso al código md del post emergente
Cuadro de contenidos de la entrada con tres niveles de títulos
Tema para el resaltado
Y lo más interesante; la posibilidad de añadir comentarios de un toot en Mastodon gracias a una extensión de Quarto Mastodon-comments.

Referencias

Tutorial en Quarto para crear un blog (sencillo y efectivo)
Tutorial en Codeberg para crear un repositorio y usar git desde la versión local (sencillo y efectivo)
Codeberg Pages para la publicación de webs a partir de un repositorio.
Creating a blog with Quarto in 10 steps (desde mac y utilizando Github)
Tutorial de Git
Deploying a Quarto website to Codeberg

Footnotes

Por supuesto, cada uno puede elegir la mejor manera de editar los archivos markdown, desde un simple editor de texto a uno de md con previsualización como GhostWriter o incluso como proyecto en VSCodium (VSCode) donde se puede instalar la extesión de quarto que incorpora previsualización

↩︎
Git puede ser muy confuso para un principiante. Si el lector es la primera vez que lo utiliza, recomiendo hacerse con los conceptos básicos en esta breve pero excelente guía.↩︎
Cuando hagamos muchos push terminaremos hartos de introducir credenciales. Una manera sencilla de guardarlas (¡ojo! En texto plano sin cifrar) es escribir lo siguiente en terminal
```
git config --global credential.helper store
git config --global credentials.helper 'cache --timeout=3600'
```
timeout indica el tiempo en segundos hasta que vuelva a solicitar las credenciasles.↩︎

--- title: "Guía de creación de un blog con Quarto" author: "Pedro J." date: '2022-12-08' date-modified: last-modified categories: [DIY] footnotes-hover: true code-tools: true toc: true toc-title: Contenidos toc-depth: 3 toc-expand: 3 highlight-style: dracula filters: - mastodon-comments mastodon_comments: user: "ecosdelfuturo" host: "mstdn.social" toot_id: "113772827104158153" --- Expliquemos de la manera más sencilla posible el proceso que he seguido para crear este blog [con Quarto](https://quarto.org/docs/websites/website-blog.html) y subirlo a _Codeberg_. Considere el lector que hasta hace relativamente poco tiempo no tenía idea de _git_ ni de _Quarto_, por lo que el proceso no debería resultar especialmente complicado para un usuario que haya hecho sus pinitos con una terminal. Por supuesto, mis instrucciones serán para linux, así que el usuario de otro S.O. tendrá que adaptarla en consecuencia (ver [instrucciones de instalación](https://docs.codeberg.org/getting-started/install-git/) de git). ## Crear repositorio El primer paso es [crear un repositorio](https://docs.codeberg.org/getting-started/first-repository/) para los archivos de configuración del blog y otro repositorio denominado _pages_ donde subiremos el contenido de la carpeta ``_site`` generada por _Quarto_ para ver el blog en la dirección [{usuario}.codeberg.pages](https://docs.codeberg.org/codeberg-pages/). ![](repositorios.png) Veremos que alternativamente se puede utiizar un único repositorio, aunque siempre será conveniente tener una web principal en _pages_ ## Crear blog Después de [instalar Quarto](https://quarto.org/docs/get-started/) vamos a la terminal y, desde la ruta que consideremos apropiada, creamos la base del blog ```quarto create-project {nombre_proyecto} --type website:blog ``` En mi caso ```quarto create-project blog --type website:blog ``` Esto nos creará el sistema básico de archivos con dos posts de ejemplo ![](archivosblog.png) Básicamente, las paǵinas editables en Markdown (``index.qmd`` y ``about.qmd``), un archivo de configuración (``_quarto.yml``), y una hoja de estilos. Cada post también tendrá su archivo md editable ``index.qmd``. Podemos ver el aspecto inicial del blog con ```quarto preview blog ``` código que genera un ``localhost`` para ver la web en el navegador, creando para ello una carpeta ``_site`` con los archivos ``html`` que serán la versión final del blog visualizable en el navegador. Lo bonito del caso es que, editando cualquiera de los archivos, la versión web se actualiza una vez guardamos los cambios de edición.[^1] ## Configuración básica del blog Vayamos ahora con la configuración básica del blog en el archivo ``_quarto.yml`` , que en mi caso ha quedado como sigue ``` project: type: website website: title: "Blog" site-url: https://pedroj.codeberg.page/blog/ description: "Nuevo blog personal de @ecosdelfuturo@mstdn.social" navbar: right: - about.qmd - icon: wordpress href: https://xclima.wordpress.com/ - icon: mastodon href: https://mstdn.social/@ecosdelfuturo - icon: code-square href: https://codeberg.org/pedroj - icon: rss href: index.xml format: html: theme: cosmo css: styles.css comments: hypothesis: true ``` La mayoría de los cambios son sólo personalización de lo que ya viene por defecto, destacando los [iconos](https://icons.getbootstrap.com/) de redes sociales, la [elección del tema](https://bootswatch.com/), y dos cosas importantes que sí que no vienen por defecto: el feed y los comentarios. _Quarto_ ofrece tres formas de añadir la posibilidad de comentarios. Dos de ellas están basadas en aplicaciones disponibles en _Github_ pero no en _Codeberg_, por lo que sólo me quedaba la tercera, [Hypothesis](https://web.hypothes.is/), una plataforma open-source de anotaciones y comentarios en la web que me ha gustado bastante, muy en la línea de la filosofía de utilizar open-source comunitario. Activarla es tan sencillo como añadir ``` comments: hypothesis: true ``` Para añadir un feed lo hacemos en el archivo ``index.qmd`` principal del blog, añadiendo la línea que vemos en la imagen. ![](feed.png) Si además queremos poner un icono de feed en la barra de navegación del blog, añadimos al archivo ``_quarto.yml`` otro icono apuntando a la dirección del feed generado ``index.xml`` ``` - icon: rss href: index.xml ``` ## Subir proyecto al repositorio remoto Ahora toca subir todos los archivos a Codeberg. Para ello utilizaremos git.[^2] El propio repositorio nos propone la manera de hacerlo. En una terminal, dentro de la carpeta del proyecto hacemos ``` git init #iniciamos repositorio git checkout -b main #nos aseguramos trabajar en la rama principal git add --all #Añadimos todos los archivos para seguimiento git commit -m "first commit" #Realizamos una instantánea (commit) git remote add origin https://codeberg.org/usuario/repo.git #Añadimos repositorio remoto git push -u origin main #Subimos el proyecto local al repositorio ``` Al hacer ```push```, git nos pedirá las credenciales de acceso a nuestra cuenta en Codeberg.[^3] ## Publicar el blog En el paso anterior hemos subido todos los archivos del proyecto al repositorio remoto. Pero ahora nos interesa que los archivos _html_ de la carpeta ``_site``, que generamos cada vez que hacemos una previsualización con ```quarto render --html ``` Puedan servirse desde codeberg como web. Esto no es tan simple de hacer correctamente, pero veremos primero una manera sencilla (aunque poco recomendable) que puede servir a quien no quiera lidiar con git en mayor profundidad. ### Servir el blog (método sencillo no recomendado) Creamos un nuevo repositorio denominados _pages_. Codeberg servirá una web alojada en ese repositorio _pages_ en la dirección _usario.codeberg.page_ Generamos la carpeta ``_site`` de nuestro blog con ```quarto render --html ``` Hacemos una copia de la carpeta ``_site`` fuera de la carpeta del proyecto. En dicha copia inciamos un nuevo repositorio local y lo subimos al nuevo repositorio remoto con los mismos comando de git vistos anteriormente. El problema con este procedimiento es que en un segundo ```push``` que hagamos después de modificar nuestro blog tendremos que tener mucho cuidado en no eliminar el archivo ```.git```de configuración en la carpeta destino de nuestra copia de ``_site``, algo que resulta muy engorroso si uno publica con frecuencia. En un segundo ```push``` sólo tendríamos que hacer ``` git add --all git commit -m "second commint" git push -u origin main ``` ### Servir el blog (método más complejo recomendado) Codeberg tambien puede servir un blog/web desde la carpeta de un repositorio que contenga los archivos _html_ necesarios siempre que estén asignados a la rama _pages_. Por ejemplo, los archivos de nuestro repositorio con el nombre _blog_ los serviría en este caso en la dirección _usario.codeberg.page/blog_ Así, ya no necesitaremos el repositorio _pages_ y podemos hacer todo desde el mismo repositorio _blog_ Actualizaremos así nuestros archivos del proyecto al respositorio con _git_ tal y como hicimos anteriormente, pero ahora repetiremos el siguiente procedimiento con la carpeta _sites_ generada creando una nueva rama _pages_ ``` quarto render --html #generamos el blog en la carpeta _sites git clone https://codeberg.org/usuario/blog.git pages.git #clonamos el repositorio remoto en la carpeta temporal ``pages.git`` rm -r pages.git/* #Borramos todos los archivos de la carpeta respetando la configuración de git rsync -av _site/* pages.git/ #Sincronizamos la carpeta ``_site`` generada con la temporal ``pages.git`` cd pages.git #Nos situamos en la carpeta temporal git checkout --orphan current #Nos lleva a una rama huéfana de commints dejando intacta la rama main git add -A #Añadimos todo los archivos al nuevo commint git commit -m "Deployment at $(date)" git branch -m pages # Cambiamos(creamos) la rama _pages_ git push -f origin pages cd .. rm -rf pages.git #borramos la carpeta temporal ``` Cada vez que actualicemos algún archivo del blog, tendremos que volver a repetir todo esto teniendo cuidado con lo errores. Por supuesto, este procedimiento puede automatizarse con un [script](https://codeberg.org/pedroj/blog/src/branch/main/script.sh). ## Formatos locales de post Este post empieza con el siguente yaml de configuración situado al principio del archivo md del post ``` title: "Guía de creación de un blog con Quarto" author: "Pedro J." date: '2022-12-08' date-modified: last-modified categories: [DIY] footnotes-hover: true code-tools: true toc: true toc-title: Contenidos toc-depth: 3 toc-expand: 3 highlight-style: dracula filters: - mastodon-comments mastodon_comments: user: "ecosdelfuturo" host: "mstdn.social" toot_id: "113772827104158153" ``` Sobre el estándar que genera quarto he añadido: - Fecha de edición modificada - Notas al pie emergentes - Icono de acceso al código md del post emergente - Cuadro de contenidos de la entrada con tres niveles de títulos - [Tema para el resaltado](https://quarto.org/docs/output-formats/html-code.html#highlighting) - Y lo más interesante; la posibilidad de añadir comentarios de un toot en Mastodon gracias a una extensión de Quarto [Mastodon-comments](https://github.com/AndreasThinks/quarto-mastodon-comments). ## Referencias - [Tutorial en Quarto](https://quarto.org/docs/websites/website-blog.html) para crear un blog (sencillo y efectivo) - [Tutorial en Codeberg](https://docs.codeberg.org/getting-started/first-repository/) para crear un repositorio y usar git desde la versión local (sencillo y efectivo) - [Codeberg Pages](https://docs.codeberg.org/codeberg-pages/) para la publicación de webs a partir de un repositorio. - [Creating a blog with Quarto in 10 steps](https://beamilz.com/posts/2022-06-05-creating-a-blog-with-quarto/en/) (desde mac y utilizando Github) - [Tutorial de Git](https://glasskube.dev/guides/git/) - [Deploying a Quarto website to Codeberg](https://danielreed.codeberg.page/posts/quarto-codeberg.html) [^1]: Por supuesto, cada uno puede elegir la mejor manera de editar los archivos markdown, desde un simple editor de texto a uno de md con previsualización como [GhostWriter](https://kde.github.io/ghostwriter/index.html) o incluso como proyecto en [VSCodium](https://vscodium.com/) (VSCode) donde se puede instalar la extesión de quarto que incorpora previsualización ![](VSCodium.png) [^2]: Git puede ser muy confuso para un principiante. Si el lector es la primera vez que lo utiliza, recomiendo hacerse con los conceptos básicos en esta breve pero excelente [guía](https://glasskube.dev/guides/git/). [^3]: Cuando hagamos muchos _push_ terminaremos hartos de introducir credenciales. Una manera sencilla de guardarlas (¡ojo! En texto plano sin cifrar) es escribir lo siguiente en terminal ``` git config --global credential.helper store git config --global credentials.helper 'cache --timeout=3600' ``` _timeout_ indica el tiempo en segundos hasta que vuelva a solicitar las credenciasles.