How This Site Works

This site is a hosted on GitHub Pages, backed by this GitHub repo, with content managed using Obsidian.

I initially set it up based on Nicole van der Hoeven’s useful guide (ironically, published via Obsidian Publish) and the Quartz docs.

Workflow

1. The notes repo is cloned on my Mac.
2. I open the cloned repo in Obsidian as a Vault.
3. I write Markdown files under the content/ directory using this template (for the “frontmatter”).
4. Run npx quartz build --serve in the root directory for local serving / preview.
5. Run npx quartz sync in the root directory to push updates to the repo that get auto-published to GitHub Pages (https://itamaro.github.io/notes/).

Some Implementation Notes

Nicole’s guide and the Quartz docs are way more comprehensive and informative. This is “quick notes” for myself.

Quartz is a generic static site generator that has first-class support for Obsidian (i.e. it “understands” Obsidian linking semantics). Install Quartz using npm in the cloned repo, and initialize:

git clone git@github.com:itamaro/notes.git
cd notes
npm i
npx quartz create

The site is built and published to GitHub Pages on push using this GitHub Actions workflow (should probably update it from time to time from its source of truth).

The repo needs to have Pages enabled in the settings with “Source” set to “GitHub Actions”.

Configuring Custom Domain

Step 1: Verify the domain following this guide (TLDR: add itamaro.com in https://github.com/settings/pages and add the TXT record to the domain DNS).

Step 2: Update the itamaro.com DNS records according to GitHub’s docs (TLDR: add 4 A Records for @ and * hostnames pointing to 185.199.{108..111}.153, and a CNAME record for www hostname pointing to itamaro.github.io).

Step 3: Update the GitHub Pages repo settings, setting the “Custom domain” option to “itamaro.com”. Wait for all the things to settle (DNS settings, SSL, caches, …).