From Quarto with love (but back to Hugo)

Quarto, Hugo, Blogging
Edited on 17.08.2023

I’ve been using different static site generators over the years - Jekyll, Hugo, and most recently Quarto. In this post I’ll share my experiences and how I’m now using Hugo and Quarto together for my blog.

Why I Switched back to Hugo #

I used Jekyll years ago (you can see one of the pages I created here), then switched to Hugo, and about a year ago I started using Quarto.

Quarto is great for scientific publishing, but I found it too limiting for a personal blog:

  • Every post must be in its own folder with an index.qmd file. This works well for showcasing content, but isn’t convenient for writing.
  • As a scientific publishing tool, the blog features remain an afterthought. The Quarto team is great about adding features, but blog improvements happen slowly.

So I decided to switch back to Hugo as my static site generator for the flexibility.

Fortunately, there’s no need to fully abandon Quarto. Quarto has built-in support for outputting to Hugo. I can use Quarto to render my posts written in qmd format into Markdown that Hugo can use.

Quarto Loves Hugo #

Here is a quick overview of how I have Hugo and Quarto working together:

  • I added some config settings to my Hugo config.toml file:
ignoreFiles = [ "\\.qmd$", "\\.ipynb$", "\\.py$" ]

  defaultMarkdownHandler = "goldmark"
    unsafe = true
  • I have a content/posts folder containing subfolders for each post, with a index.qmd file inside.

  • I put this _quarto.yml in the Hugo root directory:

  type: hugo
    code-fold: true
    html-math-method: webtex
  warning: false
  • To create post written in qmd files, I run quarto render which outputs Markdown from my qmd posts into the Hugo content folder.

I also found two nice blog posts from people using Quarto with Hugo:

Customizing the Theme #

I started from the lines theme, you can find it here.
Later I mixed it with another theme, simplist by the same author and I added my custom CSS parts.

More Customisation #

I started with the Lines theme, customised it with styles from the Simplist theme, and added some of my own CSS.

Hugo and GitHub Pages #

I followed Hugo’s GitHub Pages guide but ran into some issues:

  • The theme submodule wasn’t syncing properly. I had to manually add the .gitmodules file.
  • The theme’s example content was cluttering my published site. I forked the theme and removed the examples.

Here is my final .gitmodules file:

[submodule "themes/lines"]
    path = "themes/lines"
    url = ""

Hugo and Code Highlighting #

To get code highlighting in backticks markdown fences I enabled:

pygmentsStyle = "pygments"
pygmentsCodefences = true

Adding Comments with giscus #

I followed various blogpost with the configuration advices.
By default, giscus is adding comments to every page, but I wanted to have comments only on my posts.
I followed advice1 and I wrapped my addition of giscus partial into footer.html with if statement:

{{ if not .Params.noComment }}
    {{ partial "giscus" . }}
{{ end }}

When I don’t want to include a comments block, I am adding this in the frontmatter of the post (yaml):

noComment: true

Some other useful links:

Date of Last Edit Directly from Github #

Some advice how to set up it: Add a Last Edited Date to Posts · Make with Hugo.

One caveat: setting enableGitInfo to true in your site’s configuration file sometimes is not enough2. You have to add --enableGitInfo to get .GitInfo:

hugo serve --enableGitInfo