420360 Blog

How This Blog Actually Works (And Why Obsidian + GitHub = đŸ”„)

9 min read

TL;DR (for the impatient homies)

  • We write in Obsidian like goblins hoarding markdown loot, sync the vault into this repo, let Quartz turn it into a shiny static site, then GitHub Actions yeets it to Pages. End of movie. 🎬
  • Local edits? npx quartz build --serve gives us a vibe-check preview at http://localhost:8080.
  • Push to main and the action pipeline does the deploy dance. No FTP, no drama, just vibes.
  • Custom domain? blog.420360.xyz flexing via CNAME in quartz/static/CNAME and DNS.
  • If something explodes, check the Actions logs, touch grass, fix markdown frontmatter, rebuild, push. Repeat.

Why This Post Exists (aka “fine, I’ll document it”)

People keep asking “how does this repo actually work?” and “how do you glue Obsidian, Quartz, and GitHub without summoning a cursed merge conflict?” Consider this the canonical, slightly unhinged answer. It’s half developer diary, half ops guide, and 100% meme-powered. Bookmark it, roast it, ship it.

The Core Stack, in Human Words

  • Obsidian Vault: Where we brain-dump, link, and refactor notes. Pure markdown, backlinks, and enough graph energy to power a small moon.
  • Quartz v4: Static site generator tuned for digital gardens. Transforms markdown in content/ into a production-ready site in public/.
  • GitHub Actions: Automation overlord. On push to main, it installs deps, builds Quartz, and deploys to GitHub Pages.
  • GitHub Pages + CNAME: Hosting and domain wiring. quartz/static/CNAME + Pages settings make blog.420360.xyz the canonical home.

Folder Safari (what goes where)

  • content/: The source of truth. Notes, posts, pages. If it’s here, it’s considered canonical.
    • posts/: Long-form blog entries with frontmatter. Publish-ready once draft: false.
    • pages/: Evergreen docs like START_HERE, QUICK_REFERENCE, etc.
    • developer notes/: Meta posts like this one—dev logs, process docs, spicy rants.
    • assets/: Supporting media (css/images/js) referenced by content.
  • quartz/: The engine room. Config, components, processors, plugins, styles. Tweaks here change how the site is built/rendered.
  • public/: Build output. Generated by npx quartz build. Do not hand-edit—changes get nuked on next build.
  • .github/workflows/deploy.yaml: CI/CD brain. Runs on push to main, builds, deploys to Pages.
  • quartz/static/.nojekyll: Stops GitHub Pages from messing with our build.
  • quartz/static/CNAME: Points to blog.420360.xyz for custom domain flex.

The Obsidian → Quartz → GitHub → Pages Pipeline (step-by-step, no fluff)

  1. Write in Obsidian đŸ–‹ïž
  • Draft in the vault under content/ (mirrors repo). Use frontmatter: title, date, tags, draft.
  • Want backlinks? Use regular [[wiki-links]]; Quartz resolves them to nice URLs.
  1. Local Preview 👀
  • Install deps once: npm install (or pnpm install if you roll that way; repo uses npm by default).
  • Run: npx quartz build --serve
  • Visit http://localhost:8080 to sanity-check layout, links, tags, and memes. Fix typos before the internet sees them.
  1. Commit + Push 🚀
  • git add .
  • git commit -m "chore: update notes" (or something less feral)
  • git push origin main
  1. GitHub Actions Deploy đŸ€–
  • Workflow installs deps, runs npx quartz build, publishes public/ to Pages.
  • Progress lives in GitHub → Actions. Green check = we vibin’. Red X = read logs, fix, rerun.
  1. Live Site 🌐
  • Default Pages URL: https://woodmurderedhat.github.io/blog420/
  • Custom domain: https://blog.420360.xyz (once DNS + CNAME are set).

Frontmatter Rules (or “how not to brick the build”)

  • layout: Usually post. Quartz uses it to pick templates.
  • title: Human-readable. Also used in meta tags and listings.
  • date: ISO-ish YYYY-MM-DD. Keep it real so sorting works.
  • author: Cred. Default to woody unless you’re guesting.
  • tags: Array of vibes. Drives tag pages.
  • excerpt: Short teaser. Shows up in cards/previews.
  • draft: true to hide from build outputs. Set to false to publish. Remember to flip it!

Naming & URLs

  • Posts live at content/posts/YYYY-MM-DD-slug.md. URL slug follows file name.
  • Pages live in content/pages/ with friendly names (e.g., START_HERE.md).
  • Developer logs (like this) in content/developer notes/ — spaces are fine; Quartz handles URL encoding.
  • Assets: prefer relative links (/assets/images/...). Keep them under content/assets/ so they’re copied over.
  • Use wikilinks [[Some Page]]; Quartz resolves to /some-page when file names align.
  • For explicit paths, use [text](/path) to avoid ambiguity.
  • Keep internal media near the note or in content/assets/images/ to avoid path hell.
  • Avoid absolute Windows paths in embeds; relative paths survive sync.

Git Hygiene (no cursed merge conflicts)

  • Branching: main is prod. If you’re experimenting, branch off and PR, but solo dev can commit straight to main (you rebel).
  • Keep public/ untracked (it’s build output). Don’t edit it manually.
  • Add meaningful commit messages. Future-you will thank present-you.
  • If Actions fails, read logs before panic-pushing.

Custom Domain Flex

  • File: quartz/static/CNAME → contains blog.420360.xyz.
  • DNS: CNAME blog → woodmurderedhat.github.io (or A records to GitHub Pages IPs).
  • In repo settings → Pages: Source = GitHub Actions, Custom domain = blog.420360.xyz, Enforce HTTPS checked.

Theme & Layout Shapeshifting

  • Entry points: quartz.config.ts and quartz.layout.ts for site meta, nav, and component wiring.
  • Components: quartz/components/ holds UI bits (titles, cards, headers). Edit with taste.
  • Styles: quartz/styles/ and public/index.css (generated) guide the vibe. Prefer editing source styles, not built CSS.
  • Plugins/Processors: quartz/plugins/ and quartz/processors/ customize rendering, syntax highlighting, link behaviors.

Build Commands (tattoo these on your terminal history)

  • Local serve: npx quartz build --serve
  • Clean build (if cache demons appear): delete .quartz-cache then rerun build.
  • Deploy (CI): push to main; Actions handles it.

Frequent Oh-No’s (and fixes)

  • Broken links: Check for renamed files; use wikilinks; rebuild locally to spot 404s early.
  • Draft not publishing: Set draft: false. Yes, seriously.
  • CSS not loading on Pages: Ensure .nojekyll exists in quartz/static/ (it does). Clear cache.
  • Wrong domain: Confirm CNAME file + DNS + Pages settings are aligned. Wait for DNS propagation.
  • Action failed: Open Actions logs. Usually missing deps or frontmatter typos.

The Philosophy (a slightly chaotic manifesto)

This blog is part lab notebook, part soapbox. We optimize for:

  • Low friction: Obsidian-first authoring keeps the writing flow high. No CMS logins, no WYSIWYG rage.
  • Versioned everything: Git is the source of truth. History matters. Reverts are cheap.
  • Static by default: Fewer moving parts. Speedy, secure, cache-friendly.
  • Memetic energy: Docs don’t have to be dry. If memes help you remember the pipeline, that’s a feature.

The Long Story (strap in, nerds)

Origins: Why Quartz over $RANDOM_STATIC_SITE_GENERATOR?

Hugo? Fast but opinionated. Jekyll? Classic but Ruby dependency vibes. Next.js? Overkill for a garden. Quartz hits the sweet spot: markdown-native, backlink-aware, batteries-included for digital gardens, and zero-config hosting on Pages. It respects the Obsidian mental model—notes as nodes, links as edges—without forcing a monolithic CMS.

Obsidian as the Content OS

Obsidian is the note engine. We lean on:

  • Backlinks: Knowledge graph without manual nav menus.
  • Transclusion: Embeds keep DRY content DRY.
  • Tagging: Quick theming for Quartz to surface.
  • Folder discipline: Mirrors repo, so git diff = Obsidian diff.

We avoid heavy plugins that mutate frontmatter or file headers. Keep it lean to keep CI happy.

The Quartz Build Internals (reader-mode)

  • Input: Everything under content/ with valid frontmatter.
  • Processing: Plugins handle markdown, syntax highlighting, link resolution, RSS, sitemap.
  • Output: public/ with HTML, CSS, JS, RSS feed, sitemap, tag pages.
  • Cache: .quartz-cache accelerates builds; nuke it when weirdness appears.

Deployment Pipeline Deep Dive

  1. Trigger: Push to main.
  2. CI Steps:
  • Checkout code
  • Setup Node
  • Install deps (npm ci preferred for lockfile determinism)
  • Build (npx quartz build)
  • Upload artifact / deploy to Pages
  1. Result: Pages serves the freshly built public/. CNAME ensures custom domain sticks.

Local Dev QoL Tips

  • Use npx quartz build --serve and leave it running while editing. Hot-ish reload saves brain cycles.
  • Lint frontmatter mentally—there’s no strict linter yet, but consider adding one if you’re feeling fancy.
  • Keep image sizes sane; static hosting loves optimized assets.

Content Lifecycle

  1. Ideate in Obsidian (rough notes, bullets, memes).
  2. Draft in content/posts/ or content/developer notes/ with full frontmatter.
  3. Preview locally, fix links.
  4. Mark draft: false when ready.
  5. Commit, push, ship.

Backups & Safety

  • Git is the backup. Push often.
  • Optionally mirror the vault via cloud sync, but repo remains canonical for deploy.

Performance & SEO Cheatsheet

  • Quartz ships a sitemap and RSS. Don’t break them; keep frontmatter dates real.
  • Add excerpt for better link previews.
  • Use headings hierarchically; Quartz uses them for TOC/nav.

Accessibility & Legibility

  • Keep heading levels sensible.
  • Use alt text on images.
  • Avoid cursed color contrasts when theming.

Meme Break (because dopamine)

  • “It works on my machine” — famous last words before a red Actions check.
  • “Just one more tweak” — commits at 3:17 AM, vibes immaculate, syntax questionable.
  • “Static sites are boring” — says who? This one’s blasting at PageSpeed 100 and wearing sunglasses.

Mini FAQ

  • Can I edit public/? No. It’s a build artifact. Touch it and the next build yeets your changes.
  • Where do I put images? content/assets/images/. Reference with /assets/images/....
  • Why is my note not showing? Probably draft: true or missing frontmatter.
  • Do I need Docker? Nope. Node + npm is enough. There’s a Dockerfile if you like containers.
  • Can I use PNPM? Sure locally, but CI uses npm. Keep lockfiles consistent.

The Vibe Guide (style + voice)

  • Emojis are welcome. Profanity is seasoning—use responsibly.
  • Keep intros short, jump to value.
  • Link other notes; the garden thrives on connections.

Ship Checklist (before pushing)

  • Frontmatter valid? draft flipped?
  • Links resolve? (local preview says yes?)
  • Images present and pathed correctly?
  • Commit message not “fix stuff again lol”? (
but also, live your life.)

Future Enhancements (aka TODO, but make it fun)

  • Add a frontmatter linter to catch missing fields.
  • Consider scheduled builds to refresh caches even without content changes.
  • Add visual diffing for CSS tweaks.
  • Build a “Today I Learned” template for rapid-fire posts.

Closing Hype

This repo is a vibes-first, automation-backed, markdown-native blog stack. Obsidian keeps writing joyful, Quartz keeps pages fast, and GitHub keeps us versioned and deployed. The rest is just us, typing into the void and hoping the void leaves a nice comment. Now go write something unreasonably good and yeet it to main. 🚀

Graph View