Van distill naar quarto?

Een blog maken met quarto.

Danielle Navarro bewerking HarrieJonkman true
2022-05-31

Een jaar geleden besloot Danielle Navarro om weer te gaan bloggen en deze blog zette ze op: blog van Danielle Navarro. Ze koos voor distill, haar keuze. Destijds heeft zij een bewuste keuze gemaakt om distill te gebruiken als mijn blogging platform in plaats van een statische site generator zoals hugo of jekyll en ze heeft geen spijt van die keuze. Gaandeweg vond zij echter een paar dingen die haar dwars zaten bij het gebruik van distill. Het is echter nooit de moeite waard geweest om te overwegen over te stappen op iets nieuws omdat distill zoveel dingen heeft die zij waardeert. Tot nu toe dan.

Nu komt quarto binnen. Ook ik werk al enige tijd met distill. De ervaringen van Danielle herken ik sterk en daarom schrijf ik vanaf nu vanuit Danielle, maar kun je ook mijzelf lezen.

Quarto, volop in de belangstelling nu, biedt de belofte van een cross-platform, overall format, open source publicatietool gebaseerd op pandoc. Geïntrigeerd besloot ik er een tijdje mee te spelen, en uiteindelijk nam ik de beslissing om mijn blog over te zetten van distill naar quarto. Deze post schetst mijn proces.

(Ik ben een beetje nerveus: een blog overzetten betekent vaak dingen opnieuw programmeren. Zal het werken? Zal alles reproduceerbaar blijken te zijn? Ik hoop het…)

Aan de slag

Het allereerste wat ik doe is Alison Hill’s prachtige We don’t talk about quarto lezen. Als je een R markdown gebruiker bent die overweegt de sprong naar quarto te maken en haar samenvatting nog niet gelezen hebt, zul je er geen spijt van krijgen dat nu wel te doen. Het is een mooi overzicht op hoog niveau. Ik raad ook Nick Tierney’s notities aan over het maken van de overstap, die zijn ook erg behulpzaam. (Zelf dus ook Danielle Navarro’s blog goed gelezen en bewerkt en de presentatie van Mine Cetinkaya-Rundel gaf interessant.

Na het eigen maken van deze achtergrondinformatie, ga ik naar de get started pagina op de quarto website om het installatiebestand te downloaden.

Nu ik quarto geïnstalleerd heb, ben ik in staat om het te gebruiken om een blog te maken. Mijn oude distill blog bestaat in een project map die ik Harrie's Hoekje heb genoemd, dus ik besluit de quarto versie te maken en de map HHquarto te maken.

Er is een pagina op de quarto website die je door het proces leidt voor creating a blog blog, die ik plichtsgetrouw volg. Vanaf de terminal (Power-shell voor Windows) gebruik ik het quarto create-project commando, en er worden verschillende bestanden aangemaakt:

quarto create-project quarto-blog --type website:blog
Creating project at /home/danielle/GitHub/sites/quarto-blog:
  - Created _quarto.yml
  - Created index.qmd
  - Created posts/welcome/index.qmd
  - Created posts/post-with-code/index.qmd
  - Created about.qmd
  - Created styles.css
  - Created posts/_metadata.yml

Komende van een R markdown achtergrond, is dit erg vertrouwd:

Blog posts renderen

Er zijn verschillende manieren om met quarto te werken. Bijvoorbeeld, later in de post zal ik het hebben over de quarto commando-regel interface die je toestaat om met quarto te werken zonder door R of RStudio te gaan. Echter, als ik begin probeer ik de dingen eenvoudig te houden en ga ik voor de optie die mij het meest vertrouwd is: Ik gebruik RStudio.

Om dit te doen, is het handig om een RStudio project te hebben voor mijn blog. Met behulp van het RStudio bestandsmenu, maak ik een nieuw project vanuit een bestaande directory (d.w.z. mijn HHquarto folder), die het HHquarto.Rproj bestand en andere infrastructuur levert die nodig is om met mijn nieuwe quarto blog te werken als een RStudio project. Als dat eenmaal gedaan is, kan ik een quarto bestand openen in de RStudio editor en zie ik een vertrouwd ogende interface:

Een blog post geschreven in quarto markdown open in de RStudio editor. Merk op dat op de plaats waar je normaal de 'Knit' knop zou verwachten voor een R markdown document, er een 'Render' knop is. Die heeft dezelfde functie en is toegewezen aan dezelfde sneltoetsen als de knop 'Knit

Figure 1: Een blog post geschreven in quarto markdown open in de RStudio editor. Merk op dat op de plaats waar je normaal de ‘Knit’ knop zou verwachten voor een R markdown document, er een ‘Render’ knop is. Die heeft dezelfde functie en is toegewezen aan dezelfde sneltoetsen als de knop ’Knit

Van hieruit kan ik op de “Render” knop klikken om een enkele pagina te renderen, of ik kan naar het RStudio menu gaan en de “Render Project” optie selecteren om de hele site te bouwen. Standaard wordt de blog gebouwd in de _site map.

Aan het spelen

Vooruitgang! Ik maak vooruitgang. Maar voordat ik andere praktische dingen ga doen, heb ik eerst nog wat belangrijke zaken te regelen: wat rondspelen. Doelloos de functionaliteit van een nieuw gereedschap verkennen is altijd leuk en ik vind het een goede manier om mezelf met iets vertrouwd te maken. Ik ben al redelijk vertrouwd met R markdown en ik veronderstel dat de meeste lezers van deze post dat ook zullen zijn, dus voor het grootste deel zijn er geen verrassingen. Toch is het de moeite waard om mezelf de gebruikelijke vragen te stellen:

A comment in the margin

Als je kijkt naar de quarto article layout documentation, ontdek ik enkele aardige kenmerken. Je kunt de :::{.class} notatie om een deel van de ‘CSS class’ toe te passen op de output, zoals hier:

:::{.column-margin}
A comment in the margin
:::

De .column-margin code voor tekst in de kantlijn, maar er zijn verschillende andere commando’s die handig zijn als je plaatjes wilt afbeelden in de blog posts:

Je kunt deze instellen binnen een chunk-optie. Bijvoorbeeld, als je column: margin als chunk-optie instelt, krijgt de uitvoer een .column-margin code en de resulterende figuur verschijnt in de marge in plaats van onder de code. Op dezelfde manier zal het instellen van column: screen als chunk optie de uitvoer een .column-screen klasse geven en de uitvoer zal de volledige breedte beslaan. Hier is een eenvoudig voorbeeld, gebaseerd op het voorbeeld in de quarto documentatie:


Ik moet toegeven, ik ben al een beetje verliefd.

Opmerkingen over de YAML koppen

De YAML koppen die gebruikt worden voor blogposts zijn een beetje anders in quarto dan hun equivalenten in distill waren, en het kost me even om uit te zoeken hoe ik de YAML headers van mijn oude R markdown posts moet aanpassen voor de nieuwe quarto blog. Hier is een kort overzicht. Ten eerste, sommige velden vereisen bijna geen veranderingen:

Andere veranderingen zijn kunstmatig: - Het description veld dat ik gebruikte op mijn oude blog doet nog steeds wat het deed: het geeft een preview tekst op de listing pagina en een samenvatting bovenaan het bestand. Er is echter ook een subtitle veld dat je voor dit doel kunt gebruiken, en de uitvoer heeft hetzelfde uiterlijk en veld als mijn oude beschrijvingen, dus ik heb besloten om al mijn oude beschrijvingsvelden om te zetten naar subtitle vermeldingen. - Om een voorbeeldafbeelding te specificeren die bij een blog post hoort, gebruik je het image veld (bijv. iets als image: thumbnail.jpg) in plaats van het preview veld uit distill. - Er is een nieuw licence veld dat het creative_commons veld uit distill vervangt. Onderaan deze post zie je een “Reuse” appendix die linkt naar een licentie bestand. Om dit te genereren, heb ik een license: "CC BY" regel opgenomen in de YAML.

Andere veranderingen gaan dieper:

Een nieuwe blog maken

Oké. Tijd om aan de slag te gaan en de standaard-blog omvormen tot een quarto-versie van mijn distill-blog. Mijn eerste stap is het verwijderen van de twee posts die bij de standaard-blog zaten, en dan deze aanmaken.

Een map met een index.qmd bestand is het absolute minimum dat ik nodig heb om aan de slag te gaan met een nieuwe post. Ik veronderstel dat er andere manieren zijn om dit te doen, maar wat ik eigenlijk doe is het aanmaken van de map en een leeg bestand vanaf de terminal (om redenen die alleen God kent)

mkdir posts/2022-04-20_porting-to-quarto
touch posts/2022-04-20_porting-to-quarto/index.qmd

Om eerlijk te zijn, het gebruik van de terminal was overkill. Wat ik in plaats daarvan had kunnen doen, als ik RStudio had bekeken in plaats van de terminal, is de optie “New File” gebruiken in het bestandsmenu en dan de optie “Quarto Doc” kiezen. Dat maakt een nieuw titelloos quarto document dat je kunt opslaan op de juiste locatie.

YAML instellingen overnemen

Een handige functie in quarto websites is dat YAML velden worden overgeërfd. Bijvoorbeeld, deze post heeft zijn eigen YAML header die de volgende – en alleen de volgende – velden bevat:

title: "Een distill blog overzetten naar quarto"
subtitle: | 
  Net als Danielle Navarro recent heb ik mijn blog van distill naar quarto overgezet. Ik heb haar notities gevolgd en her en der aangepast. Ook voor mij lijkt dit op een veelbelovende zet en in ieder geval is het een interessanten test op het gebied van reproduceerbaar. 
  to be an interesting reproducibility test
author: Danielle Navarro. bewerking Harrie Jonkman   
date: "2022-05-31"
categories: [Quarto, Blogging, Reproducibility]
image: "img/preview.jpg"

Dat is een beetje eigenaardig, want veel van de metadata die nodig zijn om deze post te specificeren ontbreken. De reden dat het ontbreekt is dat ik een aantal velden in het posts/_metadata.yml bestand heb geplaatst. Deze velden worden geërfd door elke blog post. Dit is de volledige inhoud van mijn post metadata bestand:

# Bevries computer outputs
freeze: true

# Schakel banner stijl titelblokken in
title-block-banner: true

# Activeer bijlage CC-licentie
license: "CC BY"

# Default voor inhoudsopgave
toc: true
toc-title: Table of contents
toc-location: left

# Default knitr opties
execute:
  echo: true
  message: true
  warning: true

# Default author
author:
  - name: Danielle Navarro
    url: https://djnavarro.net
    affiliation: Voltron Data
    affiliation-url: https://voltrondata.com
    orcid: 0000-0001-7648-6578

# Default voor velden citeren
citation: true

De bevries optie is bijzonder makkelijk in de context van bloggen. Ik adviseer deze documentatiepagina hierover te lezen!

Dat verklaart een hoop, maar als je goed kijkt zul je je realiseren dat er niets in deze velden staat dat het uitvoerformaat specificeert! In Rmarkdown zou ik hiervoor een output veld hebben opgenomen, maar in quarto heet het relevante veld format. Omdat de output voor de hele site geldt, staat dat deel van de YAML header in het _quarto.yml bestand. De relevante regels van dat bestand zijn:

format:
  html:
    theme: ember.scss
    css: styles.css

Ik kom hier later op terug. Voor nu is het genoeg om te erkennen dat dit aangeeft dat alle pagina’s op deze site moeten worden gerenderd naar HTML documenten, en met behulp van de ember.scss en styles.css bestanden de blog stijl te specificeren.

Converteren van mijn oude posts

De tijd is aangebroken voor een beetje handwerk. Hoewel quarto compatibel is met de meeste bestaande R markdown en ik er waarschijnlijk mee weg kan komen om ze ongemoeid te laten, verwacht ik dat ik op de langere termijn naar andere talen zal overstappen, dus het spreekt me aan om nu van de gelegenheid gebruik te maken om alles over te zetten naar quarto. Het hernoemen van alle index.Rmd bestanden naar index.qmd bestanden is eenvoudig genoeg en kan programmatisch worden gedaan. Maar de meeste van mijn bewerkingen vereisen een kleine hoeveelheid handmatig knutselwerk bij elke post. Niet veel, want het is vooral een kwestie van het hernoemen van een paar YAML velden. Gezien het feit dat er maar een stuk of 20 posts overgezet moeten worden, besluit ik dat het gemakkelijker is om het handmatig te doen dan om te proberen een script te schrijven om de taak te automatiseren. Ik heb het in een middag gedaan (Nou, Danielle dan ben je sneller dan mij. Mij kostte het wel enkele dagen).

Styleren van de nieuwe blog

Tot nu toe heeft het gebruik van quarto erg “distill-achtig” gevoeld. De structuur van de blog voelt vertrouwd aan, de YAML koppen zijn vergelijkbaar in de geest (hoewel verschillend in de details), enzovoort. Als het aankomt op het aanpassen van het uiterlijk van de blog, lijkt het helemaal niet op distill, en voelt het meer als eenvoudige R markdown-sites. Quarto websites zijn bootstrap gebaseerd, en zoals besproken op de quarto theming page, komen ze met dezelfde thema’s die je misschien kent van R markdown. Als je bijvoorbeeld beslist, zoals ik deed, dat je een heel eenvoudig wit thema wil, dan zou je het “litera” thema kunnen kiezen. Om dit op je blog toe te passen, hoef je er alleen maar voor te zorgen dat je _quarto.yml bestand de volgende regels bevat:

format:
  html:
    theme: litera
    css: styles.css

Dit zorgt ervoor dat de uitvoer zal worden weergegeven als HTML objecten, gebruikmakend van het litera bootswatch thema en het toepassen van aangepaste CSS regels die je toevoegt in het styles.css bestand.

Een erg leuke eigenschap van quarto, als je SASS kunt gebruiken om stijlen te definiëren en iets weet over hoe de bootstrap SASS bestanden zijn georganiseerd,4 is dat het je toestaat je eigen .scss bestand te schrijven om je blog thema preciezer te definiëren, waarbij je toegang hebt tot bootstrap parameters enzovoort. Ik zou je sterk aanraden om eerst meer te lezen over het quarto theming system voordat je zelf met dit aspect aan de slag gaat, maar als je meer kennis (of meer domheid) hebt dan ik, dan lees je hier hoe ik mijn blog heb opgezet. Ten eerste, in plaats van te verwijzen naar het litera thema, verwijst de YAML in mijn _quarto.yml bestand naar mijn eigen aangepaste .scss bestand:

format:
  html:
    theme: ember.scss
    css: styles.css

De inhoud van de ember.scss file ziet er (bij Danielle) als volgt uit:

/*-- scss:defaults --*/

// use litera as the base
$theme: "litera" !default;

// import google fonts
@import 'https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400;1,700&display=swap';
@import 'https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400;500;600;700&display=swap';

// use Atkinson Hyperlegible font if available
$font-family-sans-serif:  "Atkinson Hyperlegible", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji" !default;

/*-- scss:rules --*/

// litera is serif by default: revert to san-serif
p {
  font-family: $font-family-sans-serif;
}

Zoals je kunt zien, doe ik op dit moment niet veel anders dan wat kleine aanpassingen aan het litera thema, maar er is potentieel zo veel meer mee te doen dan ik heb gedaan bij het opzetten van deze blog. Ik ben van plan om hier later meer aan te sleutelen!

Een RSS feed toevoegen

Mijn oude distill blog had een RSS feed, en hoewel ik erken dat het steeds meer een esoterische functie is die de meeste mensen niet gebruiken, heb ik een voorliefde voor RSS. Quarto ondersteunt dit, maar het is niet standaard ingeschakeld. Wat ik moet doen is de YAML aanpassen in het index.qmd bestand dat correspondeert met de homepage, want dat is waar ik mijn primaire lijst van berichten heb. Daarin zie ik een listing veld. Alles wat ik hoef te doen is feed: true eronder te zetten en er is nu een RSS feed voor de site:

title: "Notes from a data witch"
subtitle: A data science blog by Danielle Navarro
listing:
  feed: true
  contents: posts

De quarto sectie over feeds geeft meer informatie hierover.

Uitzetten van de site

Het voorbereiden van de site om deze uit te zetten is relatief pijnloos. Ik vond het nuttig om de quarto website optie pagina te lezen voordat ik dit deed, omdat het een heleboel instellingen noemt om aan te sleutelen, meestal in het _quarto.yml bestand. Ik kies er bijvoorbeeld voor om de navigatiebalk aan te passen, de voorbeeldafbeeldingen van de sociale media, enzovoort. Uiteindelijk bereik ik het punt waar ik tevreden ben en ga ik verder met de implementatie.

Gelukkig valt er over het uitzetproces zelf niet veel te zeggen. De quarto deployment pagina bespreekt verschillende opties voor hoe je dit kunt doen. De meeste van mijn websites worden uitgerold via GitHub Pages of via Netlify. Dit is een Netlify site, dus ik volg de instructies daar en alles gaat soepel. Dit brengt me echter wel bij een ander onderwerp…

Netlify herleidt

Ik heb mijn blog op een bepaalde manier gestructureerd. Net als de standaard quarto blog, staan alle posts in de posts map, en ze hebben een systematische naam: ze hebben eerst een ISO-8601 geformatteerde datum, en dan een semantische slug. Dus de volledige URL voor deze blog post is:

blog.djnavarro.net/posts/2022-04-20_porting-to-quarto

Dat is handig voor archiveringsdoeleinden en om alles netjes geordend te houden in mijn projectmap, maar het is ook een beetje onhandig voor het delen van links. In de praktijk is het “posts” gedeelte een beetje overbodig, en ik ga nooit twee keer dezelfde slug gebruiken, dus is het handig om het zo in te stellen dat er ook een kortere URL is voor de post,

blog.djnavarro.net/porting-to-quarto

en dat deze korte URL automatisch naar de langere herleidt.

Aangezien ik van plan ben om deze blog uit te rollen naar Netlify, moet ik ervoor zorgen dat wanneer de site gebouwd wordt, er een _redirects bestand wordt aangemaakt in de site map. Dit bestand moet één regel per redirect bevatten, met als eerste het “redirect from” pad, gevolgd door het “redirect to” pad. Hier is hoe die regel eruit ziet voor deze post:

/porting-to-quarto /posts/2022-04-20_porting-to-quarto

Ik ben niet van plan om deze regels handmatig toe te voegen, dus wat ik in plaats daarvan doe is een R chunk toevoegen aan het index.qmd bestand dat correspondeert met de startpagina van de blog, met de volgende code:

# lijst namen van de post folders
posts <- list.dirs(
  path = here::here("posts"),
  full.names = FALSE,
  recursive = FALSE
)

# extraheer de slugs
slugs <- gsub("^.*_", "", posts)

# regels om een netlify _redirect file toe te voegen
redirects <- paste0("/", slugs, " ", "/posts/", posts)

# Schrijf de _redirect file
writeLines(redirects, here::here("_site", "_redirects"))

Elke keer als deze site herbouwd wordt – wat meestal inhoudt dat de home page herbouwd wordt omdat die de lijst met berichten bevat – wordt het _redirects bestand vernieuwd. Er is misschien een schonere manier, maar dit werkt.

The quarto CLI

Iets wat ik eerder vergat te melden. Ongeveer halverwege het proces van het aanpassen van mijn oude posts om ze geschikt te maken voor de quarto-blog, heb ik besloten om RStudio niet langer te gebruiken voor de rendering, en heb ik wat tijd besteed om mezelf vertrouwd te maken met de quarto-command line interface. Ik heb nog geen specifieke beslissingen genomen over hoe mijn lange termijn workflow met quarto eruit gaat zien, maar ik vond het wel nuttig om een gevoel te krijgen voor het concept van quarto als een standalone installatie. Ik ga hier niet in detail treden, maar even kort: aan de terminal kan ik zien dat ik een aantal help opties heb,

  Usage:   quarto 
  Version: 0.9.282
                  

  Description:

    Quarto CLI

  Options:

    -h, --help     - Show this help.                            
    -V, --version  - Show the version number for this program.  

  Commands:

    render          [input] [args...]  - Render input file(s) to various document types.                                                
    serve           [input]            - Serve an interactive document.                                                                 
    create-project  [dir]              - Create a project for rendering multiple documents                                              
    preview         [file] [args...]   - Render and preview a Quarto document or website project. Automatically reloads the browser when
    convert         [input]            - Convert documents to alternate representations.                                                
    capabilities                       - Query for current capabilities (output formats, engines, kernels etc.)                         
    check           [target]           - Check and verify correct functioning of Quarto installation and computation engines.           
    inspect         [path]             - Inspect a Quarto project or input path. Inspecting a project returns its config and engines.   
    tools           [command] [tool]   - Manage the installation, update, and uninstallation of useful tools.                           
    help            [command]          - Show this help or the help of a sub-command.

Van daaruit kan ik de help documentatie voor het quarto render commando bekijken door het volgende in te typen,

enzovoort. Het doorbladeren van deze documentatie naast alle uitstekende inhoud op de quarto-website is een handige manier om extra opties te vinden. Als ik de huidige post zou willen renderen, en mijn terminal bevond zich momenteel in de hoofdmap van het project (d.w.z. mijn quarto-blog map), dan kan ik het als volgt renderen:

De mogelijkheid om dit netjes vanaf de terminal te doen lijkt een handige eigenschap van quarto, hoewel ik moet toegeven dat ik nog niet zeker weet hoe ik het zal gebruiken.

Epiloog

Toen ik aan dit proces begon was ik er niet helemaal zeker van of ik door zou zetten en de blog daadwerkelijk zou overschakelen naar quarto. De distill-blog heeft me het afgelopen tijd goed gediend en ik hou er niet van om dingen te repareren als ze niet kapot zijn. Hoe langer ik echter met quarto speelde, hoe meer het me beviel, en het proces was veel minder pijnlijk dan ik vreesde dat het zou zijn. Ik heb het gevoel dat het de dingen heeft behouden die ik leuk vind aan distill, maar deze netjes heeft geïntegreerd met andere functies (bijv. de bootstrap grid!) die ik echt miste in distill. Zo nu en dan kom ik wat kleine eigenaardigheden tegen waar sommige ruwe kantjes van quarto nog zichtbaar zijn – het is nog steeds een nieuwe tool – maar ik geniet er erg van.

Maar hier is Harrie zelf weer. Ik twijfel nog. Vooralsnog blijf ik met distill mijn blog schrijven, maar zal wel nog wat meer meer quarto oefenen.

  1. Ja↩︎

  2. Nee, maar ze kunnen recursief zijn\[\^3\]↩︎

  3. Voor het geval je geïnteresseerd bent: de “Welkom op mijn blog” post in de start blog vermeldt de datum als date: "20/04/2022", die wordt verwerkt als een letterlijke string wanneer de post wordt gebouwd (d.w.z., de postdatum wordt weergegeven als “20/04/2022”), logisch genoeg. Echter, wanneer je de hele site bouwt, wordt deze weergegeven als “4 mei 2023”.↩︎

  4. Wat ik eerlijk gezegd niet doe, maar ik ben ook dom en probeer dingen toch↩︎