justcarlson.com

My personal website and blog, built with Astro and deployed on Vercel.

Prerequisites

• Node.js 22+ (or use nvm / fnm to auto-switch)
• just command runner
• npm (included with Node.js)
• yq v4+ (mikefarah/yq, for YAML processing)
  • Arch Linux: pacman -S go-yq
  • macOS: brew install yq
  • Ubuntu: Download binary from releases

Quick Start

git clone https://github.com/justcarlson/justcarlson.com.git
cd justcarlson.com
just bootstrap
just preview

Open http://localhost:4321 in your browser.

Obsidian Integration

This blog supports Obsidian, Pages CMS, and agent-assisted draft pull requests. See the publishing guide for the complete workflow.

just setup      # Configure your vault path (one-time)
just migrate-vault --dry-run # Preview legacy frontmatter and template migration
just migrate-vault # Normalize existing blog notes with backups
just draft "Post title" # Create an unpublished Obsidian draft
just publish    # Publish posts marked with draft: false
just list-posts # List available posts in your vault

Run just --list to see all available commands.

Development

Command	Action
just preview	Start local dev server
just build	Build for production with type checking
just lint	Run Biome linter
just format	Format code with Biome

Adding Blog Posts

Blog posts live in src/content/blog/ organized by year. Create a new markdown file with frontmatter:

---
title: "Post Title"
pubDatetime: 2026-01-29T12:00:00.000+00:00
description: "Brief description"
tags: ["tag1", "tag2"]
draft: false
---

Your content here.

Common Issues

Node version mismatch Run nvm use or fnm use to switch to the correct Node version. The project uses Node 22 (specified in .nvmrc).

just command not found Install the just command runner from just.systems.

Permission denied on scripts Run chmod +x scripts/*.sh to make scripts executable.

Port 4321 already in use Another dev server is running. Kill it with lsof -i :4321 | grep LISTEN | awk '{print $2}' | xargs kill or use a different port.

Build fails with type errors Run npm run sync to regenerate Astro types, then retry the build.

Deployment

Deployed automatically on Vercel when changes are pushed to main.

Pull requests receive Vercel Preview deployments. Draft posts are included in local development and Vercel Preview builds, but excluded from production.

Credits

Built on the excellent AstroPaper theme by Sat Naing.

Forked from steipete.me with gratitude for the thoughtful customizations.

License

• Blog content: CC BY 4.0
• Code: MIT License