Host your Obsidian notebook on GitHub Pages for free

This tutorial walks you through how to publish your Obsidian notes as a website, hosted on GitHub pages. No coding required. The basic result will look like this: https://quartz.jzhao.xyz/. The look & feel is customizable but is outside the scope of this article. See quartz showcase examples.

The final workflow is shown below. You just write in Obsidian like you normally do, and run a command to publish (or configure it to automatically publish every time you save). Zero friction from idea to internet.

This doubles as an introduction to GitHub for the layperson.

(1) Create a GitHub account

We're using GitHub to host the source files, and to run the script that converts markdown into HTML (the tool that does this conversion is called Quartz, and it is open source).

• Sign up for a GitHub account: https://github.com/signup

(2) Fork the template

• Open the template here: https://github.com/DefenderOfBasic/obsidian-quartz-template
• Click "fork" to make a copy of it in your account:

• Give it a name. This will be the name of the published URL: https://<USERNAME>.github.io/<REPO_NAME>

(3) Enable GitHub Actions

Every time you make a change & push it to GitHub, the "actions" will run the script to generate & publish the HTML.

• Go to the settings page of your repo

• Click on "Pages" in the sidebar

• Change the deploy source to "GitHub Actions"

• Go to the "Actions" page of your repo

• Click the green button: "I understand my workflows, go ahead and enable them"

(Optional) Test that your site is up

At this point you can edit the files on GitHub.com in your browser and the website will be deployed. The rest of the article will be setting up the files locally so you can edit them in Obsidian.

To confirm everything so far is working, try editing the source/content/index.md file in your repo as shown below.

When you make an edit, you'll see a yellow pending circle that will turn green after a minute or so (might need to refresh).

Once it's green, see your website at https://<USERNAME>.github.io/<REPO_NAME>. You should see the words you just edited! 🎉

(4) Download the repository with GitHub desktop

In this step we'll use GitHub desktop to sync the repository from GitHub.com to your computer. This is like adding a Dropbox/Google Drive folder to your computer so you can move files back & forth from your computer to the server.

• Download GitHub desktop: https://desktop.github.com/download/
• Click Sign in to GitHub.com to connect it to your account
• Click Clone a repository from the Internet...

• Select the repository that you forked AND note the local path on your computer. You will open this folder in the next step.

• Click Clone

(5) Open the Obsidian Vault

• In Obsidian, click Open folder as vault

• Navigate to the location of the repository from the previous step, and open the folder: source/content/

(in my case the full path is C:/Users/Defender/Documents/GitHub/obsidian-quartz-template/source/content)

Now you can edit this as a normal Obsidian vault. This should come configured with the Git community plugin. To push your changes:

• Ctrl+P (or Cmd+P on macOS) then type Git sync to get the option

• Go to GitHub.com, you'll see the yellow dot, and green arrow eventually

---

Thanks for reading! Please let me know if you have any questions/get stuck and we can improve this guide!

I really believe a lot of value in society is unlocked when the layperson understands the basics of working with technology. I think putting something on our species' planetary network is as basic of a need as using the telephone. I've written a couple things in service of this:

• Get your own piece of internet real estate in 5 minutes -> how to host your website with Glitch.com and write basic HTML. Another good, free static hosting option that is as easy as editing a google doc.
• Your first bookmarklet -> how to automate little actions in your workflow, especially now with ChatGPT generating the code so you don't even have to code, can just describe what you want & wire it up.

This Obsidian / Quartz template contains a source/raw_html folder that is copied into the final build. This means you can use this to deploy any arbitrary HTML, generate something from your favorite LLM and paste it here, or create a personal archive of web pages that are important to you.