How I created this Blog

Blogging is an essential part of the Fast.AI methodology, therefore, I decided to follow the advice and start my blog to document my “Machine Learning Journey”. Here are the steps it took to create this blog.

The previous goto solution “Fastpages” has been depreciated in favor of Quarto. There is a good tutorial, but honestly I found it a bit intimidating because it is not a simple step-by-step guide, also the Creating a Blog page did no quite fit this category (for me). Therefore, without being an expert at this, let me share what I did to create this blog.

So if your goal is to create a simple blog based on Quarto, just hop on and follow along :).

A little side-note: This is the fourth blog post I write with Quarto, and by now I feel that some rough edged have been removed, mostly because I realized that really all the blogging can be done in jupyter notebook! Therefore, learning, running my own experiments and blogging happen in the same environment and with a lot of reuse. Knowing that my more things can be done, the only goal of this blog post is to get you up and running with a basic setup and explain the possibility to blog via jupyter notebooks.

Step 1: Create a new GitHub repo

Your blog will reside in a GitHub repo, and it will leverage Github Pages. Follow steps 1 and 2 on the GitHub Pages homepage for the initial setup.

Note: The default recommendation for the repo is <your username>.github.io. I took that recommendation, but anything else should work as well.

As a result you have an empty repo with just a readme.md file. Here’s how it still looks in my repo.

For cloning the repo to my local machine, I did:

git clone git@github.com:chrwittm/chrwittm.github.io.git

Two final activities are needed to finalize the setup of your repo:

• Create a new branch called gh-pages. To do this, go to your branches (for me that is https://github.com/chrwittm/chrwittm.github.io/branches), and create the new branch by clicking the “New branch”-button in the top right.
• Set the new branch as the branch for GitHub Pages. In your repo, navigate to Settings -> Pages. (In my repo that takes me to https://github.com/chrwittm/chrwittm.github.io/settings/pages.) Change main to gh-pages.

For more info on setting the branch, please refer to the Quarto Docs.

Step 2: Install Quarto

I am currently working on a Windows 10 machine and I usually work both in WSL (Ubuntu) (e.g. for Jupyter and anything related to Fast.AI development) and in Windows with VS Code (e.g. for writing this blog).

Installing Quarto in WSL

From previous activities with nbdev, I already had Quarto installed. If I re-traced my steps correctly, here is what I did (as suggested here and here):

mamba install -c fastchan nbdev
nbdev_install_quarto

Installing Quarto for Windows (optional)

Optional: Once I discovered that I can do everything in jupyter, I would label this step as optional, because I only used the Windows installation of Quarto to render previews of .qmd-files - which I do not need anymore when everything is done in jupyter notebooks.

Go to this page, download and install Quarto.

Setup Addons for VS Code (optional)

Optional: Once I discovered that I can do everything in jupyter, I would label this step as optional, because I only used the Windows installation of Quarto to render previews of .qmd-files - which I do not need anymore when everything is done in jupyter notebooks.

I also installed the Quarto extension for VS Code.

Step 3: Initial setup to publish “Hello World”

By now we are really close to publishing the “Hello World”-version of our blog: In the command line, go to the directory of your repo, and run the following commands, and the example content for the Quarto blog should be published to your repo.

quarto create-project --type website:blog
quarto publish gh-pages

Once done, you can open your blog at: <https://"your username".github.io/>

For some more background on what is happening with these two commands, please refer to this this page (choose “Terminal”) and this page.

Step 4: Create your first Blog Post

Now it is time to create your first own blog post.

In the posts-directory, create a new folder, for example hello-world. Within this folder, create a notebook called index.ipynb. Add some hello-world content and a RAW-section as the first cell with this content (here is an example):

---
title: "Hello World"
author: "Your Name"
date: "2022-01-01"
---

Republish your blog:

quarto publish gh-pages

Congratulations, you just published your first blog post!

For a little more detailed version of the hello world blog post, please refer to my other hello world post.

Step 5: Avoiding Disaster

When you run quarto publish gh-pages, your blog posts are rendered, and the rendered versions are pushed to git in branch gh-pages. Your actual notebooks are not uploaded to GitHub. Also any config you make to the blog etc. is uploaded in the rendered versions only. So if something were to happen to your local files, your work would be lost. (Such a disaster almost happened to me but the OneDrive file history saved me.)

Therefore, I would recommend to also upload the “source”-files to GitHub (in the main branch):

git add posts/
git add _quarto.yml
git add about.qmd
git add index.qmd
git add profile.png
git add styles.css
git add .gitignore
git commit -m "uploaded source files"
git push

As a result, the source files are also stored on GitHub.

Steps 6 to n: Additional setup

There are many more things that can be done with the blog, but to keep things down to basics, let me just mention a few topics which will make the blog look like your own blog.

Additionally, let me mention one other blog post as a reference which I found only when looking into more detailed setup topics like comments and analytics. Albert Rapp’s blog post The ultimate guide to starting a Quarto blog truly is a great guide for setting up your Quarto blog.

Step 6.1: Remove example content

Now that the hello world blog post is published, you can remove the default content. I just turned the two example blog posts into drafts by adding the following line in their headers:

draft: true

Step 6.2: Update remaining example content

Update the following files and add/change the content, so that the blog looks like it is your blog:

_quarto.yml
about.qmd
index.qmd

Conclusion

Setting up the blog was not really hard, but it took some time for me. Hopefully, this guide contains some shortcuts for you. Happy blogging!