How do we create this website and blog with Quarto

This website and blog is created with Quarto, inspired by this fast.ai post: nbdev+Quarto: A new secret weapon for productivity. nbdev is a fantastic tool, so we believe it couldn’t be wrong to go with Quarto. Here is how we did it.

Create the website scaffolding

We installed Quarto from here. After a quick review of the documentation, our first question was whether to use the Website mode or Blog mode. Sam Csik answered this exact question in her excellent post. Since a blog is simply a part of a website, we found it more flexible to create a website with a blog. Let’s start with the website.

We will use the command line in a Mac terminal, and we will name it inweb3.github.io, where inweb3 is our GitHub username (you should replace it with your actual username). Using inweb3.github.io will make it easier later to use GitHub Pages for publishing and hosting.

quarto create project website inweb3.github.io

This command creates the scaffolding for the website, with inweb3.github.io being the project’s root directory. We are given the option to open it in VSCode. We can then edit it in VSCode and preview it in an embedded window within VSCode.

Alternatively, we can navigate to the project directory using cd inweb3.github.io and preview it directly in a web browser using the preview command.

quarto preview

The preview command is a way to render the pages during the development process and visualize them. However, a more thorough rendering process that should be done before deploying the site is supported by the render command.

quarto render

Manage the Website Through GitHub

Now, let’s initialize a Git repository since we want to manage the project with git and publish it through GitHub Pages.

git init
git version
git status

This will show that the local branch we just created is named ‘master’. To match the default branch that GitHub will create, which is ‘main’, we should change our local branch name as well:

git branch -m main

We can make this a global configuration so that it will be done automatically next time:

git config --global init.defaultBranch main

Now, let’s add our files to the repository and commit them:

git add .
git status
git commit -m "initial commit"

Next, we’ll host our repository on GitHub. First, create a remote repository on the GitHub website using the same project name inweb3.github.io. To avoid commit conflicts later when we push to the repository, we should create it with the default settings (without selecting a README.md, license, or .gitignore file). These files can be added after the local and remote repositories have been synced.

Now, follow the instructions presented on the screen to connect the local repository to the remote one:

git remote add origin https://github.com/inweb3/inweb3.github.io.git
git branch -M main
git push -u origin main

After this, use git remote -v to confirm the origin has been set:

❯ git remote -v
origin  https://github.com/inweb3/inweb3.github.io.git (fetch)
origin  https://github.com/inweb3/inweb3.github.io.git (push)

Refresh the GitHub repository website to see the uploaded files.

We can then add the files that were left out in the prior stage in the inweb3.github.io (project root) directory (gitignore etc.)

Host the website on Github Pages

Add output-dir: docs to _quarto.yml

project:
  type: website
  output-dir: docs

Add a nojekyll file to stop GiHub Pages from auto processing our site using the default Jekyll tool.

touch .nojekyll

Then we can render the website and push it to Github:

quarto render  # creates the docs directory
git status
git add .   # adds both the docs directory and the .nojekyll file
git status
git commit -m "Publish site to docs/"
git push
git status

We still need to configure the Github Settings->Pages->Build and deployment->Branch and change it from the default /(root) to /docs

Wait for a few minutes, and our website will be ready at https://inWeb3.github.io. We can also check out the Actions tab to see the build and deployment logs.

Before we proceed to customize the pages, let’s clean up the repo a bit. We do not need the default _site directory in the repo now that we have used docs as the publishing directory. Add /_site to the gitignore and delete the existing files.

git status
git commit -am "delete -site"
git push

We can also clean up the temporary files in the .quarto directory in the repo by adding /.quarto/ to the gitignore file.

If there are prior files in the directory already committed, we can clean them with:

git rm -r --cached .quarto/
git commit -m "clean .quarto"
git push

If we are creating a website for particular project, we can publish it through a specific gh-pages branch, instead of the docs folder of the main branch. Here we are dedicating this repo for the website, we just use the main branch.

Customize the Website Content

Landing page

We can tackle the index.qmd file first. The quickest way is to replace it with the template provided by quarto for the about page This will become the landing page of the website.

Optimize website appearance

Use _quarto.yml to update site-wide page rendering configurations. For example, page-layout: full will make page content spread most of the page width. We can also switch to other available Bootstrap themes and specify both a light and dark theme.

# _quarto.yml
format:
  html:
    theme: 
      light: zephyr
      dark: solar
    css: styles.css
    toc: true
    page-layout: full

Add new pages

First create a new file, e.g., resources.qmd in the docs folder. Then add it to the navigation bar in _quarto.yml

website:
    title: "inWeb3"
    navbar:
        left:
            - href: index.qmd
              text: Home
            - about.qmd
            - href: resources.qmd
              text: Resources

Note that href contains the file name while text is what should be displayed in the navigation bar.

Create the blog

Now let’s refer to Sam’s another great post to add a blog to our website.

Create the blog folder and metadata file

create the posts directory under the project’s root directory inweb3.github.io. Add the posts.qmd entry to the navigation bar in _quarto.yml similar to what we did for resources.qmd.
add a _metadata.yml file under /posts. Here we can add any options that will apply to all posts in this folder. For example, re-rendering posts only when their source file changes:

# https://quarto.org/docs/projects/code-execution.html#freeze
freeze: auto

However, if we have posts that include computations, we might want to set freeze: true because prior code might have problem re-rendering after a period of time if the packages used have changed. See Freezing Posts for more details.

create a posts.qmd file in the root directory as a listing page that automatically generated index for the list of posts. Specify how the listing should be generated based on many available options. In the following example, the posts will be listed in grid format and sorted by date and title and have categories listed as well.

title: "Blog"
listing: 
  contents:
    - posts
  type: grid # table, default
  sort:
    - "date desc"
    - "title desc"
  categories: true

Create a new blog post

Create a subdirectory for the post (each post requires a subdirectory), so we can use the title of the post linked with hyphens as the directory name, e.g., this-is-a-great-post. This name will be part of the URL for the blog post.

The content of the post should be placed in an index.qmd file under this directory. There are many configurations we can set for this post. Some examples are:

---
title: "This is a great post"
description: "brief description of the post"
image: profile.jpg  # this is the header image
author: 
  - name: Charles Shen
    # affiliation:
    # email:
    # url:
date: "4/6/2024"
date-modified: "4/7/2024"
categories: [Quarto, IT]
citation:
  url: https://inweb3.github.io/posts/this-is-a-great-post
draft: false # toggle this option to publish or not
---

For more details see authoring Front Matter.

Note that we can create multiple directories similar to the posts directory and multiple listing pages as well!

Troubleshooting

If the post does not show up in the listing page, but the acutal post’s html file exists, check whether the post’s draft metadata has been set to true!
Do not add files to or modify the auto-generated docs directory. We should work with the rest of the root directory!
Run quarto render when unsure about the rendering.

Future Work

We only had time to complete the process listed above. Therefore, we will move the remaining parts to our to-do list and provide a number of valuable references we discovered.

Website and Blog Customization

Further customize and improve the site:

Customizing Quarto Websites - Make your website stand out by Sam Csik
The ultimate guide to starting a Quarto blog by Albert Rapp

Site Configuration

Set up GitHub Action to automate the process
Set up custom domain

Workflow

Set up a full Markdown workflow:

Daniel Kapitan’s Post on “How to integrate Calibre, Quarto, Obsidian, Syncthing, reMarkable to make the most of a fully integrated markdown-based workflow for reading, thinking and writing.” looks very intriguing.

Additional Resources

Citation

BibTeX citation:

@online{shen2024,
  author = {Shen, Charles},
  title = {How Do We Create This Website and Blog with {Quarto}},
  date = {2024-04-07},
  url = {https://inweb3.github.io/posts/how-do-we-create-this-website-and-blog-with-quarto/},
  langid = {en}
}

For attribution, please cite this work as:

Shen, Charles. 2024. “How Do We Create This Website and Blog with Quarto.” April 7, 2024. https://inweb3.github.io/posts/how-do-we-create-this-website-and-blog-with-quarto/.