start is difficult, but it is the easiest part

As a PhD student, there are always many things happening at the same time, both professionally and personally. Thus, finding time during the day to write sometimes seems impossible. It is the reason why making the first post is the easiest part, but maintaining the motivation and the discipline is the most difficult one. Nevertheless, we are here again, and I would like to dedicate this post to Quarto and its interaction with Jekyll (the reason I was late publishing my second post). Let’s start

What is Quarto and why is it my favorite?

Although Quarto is well-defined in its official documentation, I prefer to think of Quarto as a framework that integrates different technologies to create outstanding, high-quality documents that are interactive, reproducible, and publishable.

Currently, Quarto supports R, Julia, Python, and Observable. You can integrate it in notebooks such as Jupyter, RStudio, or VS Code or simply render it in your terminal. One of my favorite features of Quarto is the fact that for every single type of document that, as scientists, we should produce, it is possible to create it in Quarto. Additionally, the documentation is excellent, which is why Quarto is easy to learn. However, the best part is that it is open source. <3

I encourage you to start! I promise you will never regret it! (How to start in QUARTO)

Jekyll and Github

On the other hand, Jekyll is a website generator that works very well for creating portfolios, blogs, wikis, and more. It is the language that the GitHub page uses to host websites.

There are many templates that people can clone, edit, and use for personal proposals. If you prefer writing documents directly in markdown (.md), you won’t have any problem. The routine is to create a markdown document (.md) and save it in your _post/ folder. In this case, you do not need to render the document; as soon as you commit and push your changes, GitHub Pages will build and deploy your website.

A basic Jekyll site structure looks like this:

my-blog/
├── _posts/
├── assets/
├── _config.yml

The problem arises when you do not want to create the documents completely in markdown (.md) but want to use Jupyter or Quarto and integrate it into your Jekyll site, which uses liquid layaout.

Quarto in a Jekyll site, it wasn’t straightforward

After two weeks of trying to solve the problem, I have identified three solutions for integrating Quarto docs into Github Pages. I won’t elaborate on the first two solutions, but I will explain the third one, which was how I solved my problem.

Solution 1:

From a basic Jekyll site, you can edit your file configuration YAML file (config.yml) and link your pages in HTML. Previously, you had to build those pages using Quarto and render them as HTML files. Then, you could link the HTML. A lovely example is Prof. Jarrett’s website for Biol 607. If you check the config.yml file, you will notice that every linked HTML file is a page that he rendered in Quarto.

Solution 2:

Another option is to edit your workflow directly. It is a file called “workflow” inside your hidden folder .github/. If you cloned your repository locally, it will create some hidden folders that contain the routines to communicate with your remote repository through Git and instructions on how to build the website once you push your changes to GitHub.

$ alarconvv.github.io % cd .github

$ .github % ls

CODEOWNERS  no-response.yml stale.yml
config.yml  settings.yml    workflows

$ nano workflows

Thus, you could include in your workflow file a code block that allows GitHub to render a Quarto document (.qmd) as HTML automatically. Notice that I am saving my .qmd files in a folder called quarto_posts/ and rendering them in the _posts/ folder.

name: Render Quarto posts to HTML
  run: |
    mkdir -p _posts
    for f in quarto_posts/*.qmd; do
      [ -e "$f" ] || continue
      BASENAME=$(basename "$f" .qmd)
      OUTFILE="_posts/$(date +%Y-%m-%d)-${BASENAME}.html"
      quarto render "$f" --to html --output "$OUTFILE"
    done

That means your folder structure should look like this:

my-blog/
├── _posts/
│   ├── report.html
├── assets/
├── quarto-docs/
│   ├── report.qmd
├── _config.yml

Solution 3:

The last solution I know, and the one I am using, is not the most elegant or clever, but it works! This solution is practical, especially for websites that use a layout with liquid (See my web code).

If the document is only text (i.e., it does not include any code blocks), I write it as a Markdown document (.md). Then, I include a YALM block at the beginning with the instructions, tags, and items that liquid format will take to integrate this post into the website. Then, I save this .md file directly in my _post/ folder. Push changes, and Github will do the rest.

It is the YAML block I used for my first post.

---
layout: post
title: "Why I’m Starting This Blog"
date: 2025-04-07 15:09:00
description: Documenting my journey through the qualifying exam — writing to learn, reflect, and grow.
tags: [quals writing motivation]
categories: posts
featured: true
---

Hi! There! ---> the rest of the document.

However, most of my posts will include chunks with code in R or Python. In that case, I write the document in Rstudio as usual. Then, I render it as HTML directly in Rstudio or using the command line in my terminal.

quarto render YYYY-MM-DD-title-of-post.qmd --to html

Finally, I open my HTML file in a text editor and add YAML block at the top of the file.

---
layout: post
title: "Using Quarto with Jekyll"
date: 2025-05-28
tags: [r, quarto]
categories: [blog]
description: "How to integrate Quarto HTML output in Jekyll blog"
---

  
-----> My HTML file starts here -------->
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>  

Save changes and move it to my _post/ folder. Commit and push the changes. Thus, my blog will be updated automatically by GitHub Pages.

I could have converted my Quarto document (.qmd) into a Markdown document (.md). However, the liquid layout does not recognize the format, and my post loses the aesthetic when GitHub builds and deploys it.

It is simple, not elegant, but a practical solution, and it allows me to control the tags ;)

Now, I feel comfortable using my favorite document generator without changing my lovely Jekyll template. After two weeks of looking for a solution, I finally did it. Now, I do not have any other excuse to delay writing and updating my blog.