Since I am not much of a social media user (never have been), I have come to think about personal websites as a useful way to still have a presence on the internet, either as a way to share what I’m up to or as a sort of virtual business card. However, I am also neither a professional web developer nor willing to spend money to make something as simple as a ‘static’ webpage. Luckily, I did not have to and you should not have to either.
As it turns out, there are multiple frameworks you can use to quite easily make a website, using almost zero actual web development code (think: HTML, CSS, JavaScript), although knowing these certainly helps. Some of the popular open-source ones include Jekyll, and Hugo, but today I want to talk about Quarto, which is particularly useful if you use \(\LaTeX\) or want to show off some code/computations.
Quarto, which is an open-source project developed by Posit, the company behind the popular IDE called “RStudio” is actually much more than just a framework for creating websites. This project really was intended to unify a series of different R-markdown extensions people wrote over the years. This means you can use Quarto not just for websites, blogs, and code notebooks, but also data dashboards, books, presentations, and who knows what else.
If you’re not familiar with R-markdown, it’s essentially how people who code in R prefer to have code and text in one file (like a Jupyter notebook, if you know that). If you don’t know any R, don’t worry. Despite the historic links to R, Quarto is actually completely language and IDE agnostic. The only languages required for setting up a website with Quarto are Markdown, which can be learned by anyone with 5 minutes to spare, and YAML, which also can be learned as you go along.
If you want to use the code and files I will be sharing, some knowledge of Git (version control software) will be valuable. Bash (the language that terminals on Linux and Mac OS use) will also be helpful. If you don’t know anything about git and terminals don’t worry too much, as I’ll try to make it as approachable as possible here by showing you how I did it. If in doubt, I encourage you to search for the relevant information you need, or perhaps use the AI model of your trust. I personally think that Git is the hardest part about copying my set-up as it’s something people who don’t write a lot of code are unlikely to know very well. Luckily, the commands we will be using are quite basic, so it should not be too hard to find the information you need if you get stuck.
So let’s get started, shall we? We can use Quarto to render Quarto markdown (.qmd) files into HTML which will be hosted on a Github server, enabling us to have a publicly available website. The files have to be hosted on a server connected to the internet if you want other people to be able to see the website. If you want to host your code somewhere other than Github, my incoming blabbering about Git and Github might not be terribly relevant to you. Instead, you should probably check out this site once you’re ready to show off that shiny new site.
Installation and setup
First, you’ll need to install Quarto and Git. For Git, there must be endless tutorials, just search “How to install git on [your operating system]”. For Quarto I’d encourage you to just follow their guide on their website for this, as there really is nothing much I can add to this part of the process. Then, for actually setting up the website project, their guide is perfectly comprehensive. It’s only after this step where you would have to dig deeper in the documentation (which you should definitely be reading after giving my suggestions a shot) and experiment yourself to figure out how to achieve the website of your dreams, so hopefully this is where sharing my process will actually start to be helpful.
Key files and commands
Now with your project initialized. Let’s quickly highlight some of the important files and concepts. The most important file is the _quarto.yml file, which basically controls the high-level structure of the website and some of the global settings. I’ll assume you have figured out how to render and preview the files you currently have in place from the guide on how to create the project. As you should be able to see with the default files, each page is a .qmd file.
If you haven’t yet, just render the files to get a first feel for what the final product looks like. Rendering and then previewing should open your browser, with the site your files give rise to displayed. If not, you are probably overdue some bug hunting. Keep in mind that our preview showing in the browser does NOT mean that the website is public!
Let’s go over what each section does. In the project header, one important thing to note is the output-dir. Here, I specify that I want Quarto to render the files we will host later into the directory called _site. This will be a sub-directory in your project folder and can have any name. The reason we are not rendering to the root project directory is that Github really does not like this, and may fail to host your site as a result.
In the website header, I have the field “favicon”. If you don’t yet know, a favicon is the little image that websites feature on your browser tab, most commonly their logo. In the field, I simply specify the relative directory (relative in the sense of within my project files) in which the image I would like to use sits. I made my favicon using favicon.io.
The “page-footer” field displays a message of your choice at the bottom of each page in your site. In this case, I embedded a link into the string with HTML. In case you don’t know HTML, its the stuff between .
In the “format” section, I basically specify the themes of my website, one dark theme and one light theme. The built-in themes can be found here. If you specify one dark and one light theme, Quarto will add a toggle for people to switch between them in the navbar. The order of the fields determines which one is active by default. So in my case, the page is dark by default. In the dark and light fields I also add some .scss files that basically just change the color of the navbar and the font. This can get a little more technical so don’t worry too much about it if you like one of the built-in themes.
Finally, in the “extensions” field I add the copy-button extension which allows people to copy the code from any code chunks I am embedding in one click. There are actually tons of cool extensions you can use, which are linked here.
Setting up a blog within the website
A blog is a nice place to share things in posts. In Quarto, that basically means having a list of pages on a blog index page. The pages listed on this index all sit inside a folder inside your project directory. In case you didn’t realize yet, every quarto markdown document has a so-called “YAML header” which is indicated by the three hyphens that denote the beginning and ending of this header. The header specifies fields and settings for that page alone. Here’s what the header looks like for my blog index.
So in my case, I give my blog_index.qmd a title, choose a layout for my blog (there are a couple of options here), some fields that will be shown in my blog such as how long it takes to read the post (again, there is a list of things you can easily put here). The contents field specifies the folder that features all the pages I want to be listed on blog_index.qmd.
The next couple fields add UI for sorting/filtering and the categories field allows you to add category tags to posts which can be nice. I’ll show you how to add categories to posts in a second. The feed field enables RSS feed generation, meaning people will be able to follow updates to your blog with RSS. I plan on making a post about RSS at some point, so look out for that if that caught your interest.
With this in place, here is what the header of a given blog post looks like for me:
Code
---title:"My first DIY web-app"description:"Just a quick post to test the blog and brielfy talk about my first ventures into JavaScript"author:"Luke"date:"07/21/2024"categories:- webdevimage:"images/luke-23.jpg"comments:utterances:repo: lukmayer/site_commentstheme: github-darkissue-term: url---
The only thing that might be unexpected here is the comments field, where I configure a piece of software that allows people to comment on posts with their github accounts. I will not be covering how to set this up, but if you’re interested in having this also be part of your website look here.
Hopefully, you have a decent idea of how to achieve a blog on your webpage now!
About pages
Quarto provides some templates for easily configuring a rather stylish “About the author” page. Here is how I set up mine:
The documentation for these is super easy to understand and can be found here. There are a couple templates to select from and at the bottom I add some links to other things related to me. This YAML stuff should start to look familiar at this point ;) .
Hosting + My shell script for pushing updates to Github
If you want to host your finished site on Github, you need to initialize a local git repository in the directory that holds the rendered files. In my case that is the _site folder. Then you push these files to a Github repository that you named [yourgithubusername].github.io. Then, on the settings page of this Github repository you enable pages. If you struggle with this step, AI tools might be more helpful than the average search for this kind of debugging.
Because I have my website source files on a different repository on Github, I created a little shell script that I can push updates to both repositories with:
Code
#!/bin/bash# Build the site with Quartoquarto render# Push file changes to mastergit add .git commit -m "Update website code"git push -f origin master# Navigate to the _site directorycd _site# Initialize a new Git repositorygit initgit add .git commit -m "Deploy updates"# Force push to the gh-pages branch of the GitHub Pages repositorygit remote add origin git@github.com:lukmayer/lukmayer.github.io.gitgit push -f origin master:gh-pages# Clean upcd ..rm -rf _site/.git
The script essentially just runs a couple standard commands. First, I render my website and push the source files to their repository. After this, I change to the folder with the rendered files and force push these to the repositories that hosts the website. Then I remove this nested git, just in case it causes problems with the root-level git.
With this script my workflow basically just becomes: 1) Make changes, 2) open terminal, 3) go to source directory, 4) run deploy.sh (the shell script). If you plan on using this script, keep in mind that your repository will be a different one than mine, which is further complicated by the fact that I use SSH, which will require a tutorial to set up if you are not familiar (search: “how to set up SSH with Github”).
Conclusion
So that’s it! I hope you have a good idea of how to configure a website using my approach. There are a few tricks my website uses that I didn’t cover here but I encourage you to just check my source files if you see something that catches your interest. My source repository is public, meaning that even if you found this all still a little much, with some git skills you could just grab my source code and use it as a template to get started with!
From here, you should definitely also check the Quarto documentation mentioned above. It’s currently not always extremely detailed for all possible configurations and setups but it gives you a pretty good idea of what is possible.