A personal engineering journal and portfolio site built from scratch. No CMS, no managed platform, no unnecessary dependencies.

Goals

  • Markdown-first. Every post is a plain .md file with YAML frontmatter. No proprietary format, no lock-in.
  • Obsidian-compatible. The src/content/posts/ directory is intended to live inside an Obsidian vault so writing and publishing share the same environment.
  • Git-native publishing. A git push to main triggers a GitHub Actions build and deploys automatically — no separate publish step.
  • Static output. No server, no runtime, no maintenance surface. HTML files hosted anywhere.
  • Free hosting. GitHub Pages, no billing.
  • Custom domain. Public identity at hgfs.dev.
  • Multi-section theming. The journal uses an IBM-inspired dark theme. The portfolio (this section) uses Catppuccin Dark. Themes are JSON files; layouts inject the appropriate CSS variables at build time.

Architecture

Obsidian (authoring)
  → src/content/posts/ (Markdown files)
  → git push → GitHub
  → GitHub Actions → astro build
  → GitHub Pages → hgfs.dev

Each layer has one responsibility. Astro handles content collection, routing, layout, and syntax highlighting. GitHub handles version control and CI/CD. GitHub Pages handles hosting.

Tech stack

Layer Tool
Framework Astro 7.x
Language TypeScript
Content Markdown + Astro Content Collections
Syntax highlighting Shiki (custom IBM theme)
Fonts IBM Plex Sans / IBM Plex Mono
Hosting GitHub Pages
CI/CD GitHub Actions
Authoring Obsidian
Domain hgfs.dev (Cloudflare DNS)

Design system

Two themes ship as JSON files in src/themes/:

  • IBM — near-black background (#050709), red accent (#cc4444), IBM Plex typefaces. Used by the journal.
  • Catppuccin Dark — Mocha-palette background (#010101), blue accent (#89b4fa), same typefaces. Used by the portfolio.

BaseLayout.astro accepts a theme prop and injects the appropriate CSS custom properties into :root at build time. No runtime switching, no JavaScript for theming.

Outcomes

  • Journal live at hgfs.dev
  • Custom domain configured via Cloudflare DNS → GitHub Pages
  • GitHub Actions deploy on every push to main
  • Two themed sections (journal / portfolio) from a single Astro build
  • Markdown posts authored in Obsidian, published via Git

Status

  • Astro project with TypeScript
  • Content collection with category-based routing
  • Dynamic post routes
  • IBM visual identity and custom Shiki theme
  • CSS variable-driven theming
  • Portfolio section with Catppuccin Dark theme
  • GitHub Actions CI/CD
  • GitHub Pages + custom domain (hgfs.dev)
  • About page
  • Tag filtering
  • RSS feed
  • SEO metadata and sitemap
  • Obsidian vault integration