CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a personal website and blog for Michael Moores (moores.dev), built with Quarto as a static site generator. The site showcases professional experience as a solutions engineer, case studies, blog posts, and resume information. The project uses Quarto’s book format to generate a navigable site with sidebar navigation.

Development Commands

Preview and Build

# Preview site locally with live reload (runs on http://localhost:4200 by default)
quarto preview

# Render the full site to docs/ directory
quarto render

# Render a specific file
quarto render path/to/file.qmd

Quarto Version

Current version: 1.6.40

Project Structure

Core Configuration

  • _quarto.yml - Main configuration defining:
    • Project type (book)
    • Output directory (docs/)
    • Site metadata (title, URLs, search)
    • Navigation structure via chapters
    • Theme and formatting (cosmo theme, simple callouts)

Content Organization

Published Content (in project root): - index.qmd - Landing page with personal introduction - resume.qmd - Professional experience and highlights - contact.qmd - Contact information - further-reading.qmd - External resources and links - cases/ - Case studies showcasing professional work - jukebox.qmd - Case study on product management and solutions engineering - blog/ - Blog posts on technical and professional topics - index.qmd - Blog landing page - se-complexity.qmd - Draft post on solutions engineering roles

Working Directory (working/): - Contains drafts, plans, skeletons, and notes for future content - Not published to the site (not in _quarto.yml chapters) - Organized by content type (cases/, blogs/, intermediary/)

Output Directory (docs/): - Generated HTML, CSS, and assets - Served as GitHub Pages site - Do not manually edit files here - they’re regenerated on render

Content Development Workflow

Content progresses through stages in the working/ directory before publication: 1. Planning documents (-plan.md, -questions.md) 2. Skeleton drafts (skeleton.md) 3. Expansive drafts (draft.md, *-expansive.md) 4. Final QMD files in root or content directories

Brand Voice and Editorial Guidelines

The repository includes comprehensive writing guidelines in working/:

Brand Voice (working/brand-voice-core-guidelines.md): - Core philosophy: “I know nothing and can be wrong” - demonstrate expertise through acknowledging limitations - Failure as core narrative - analytical dissection without forced inspirational lessons - Show don’t tell - excruciatingly important - Plain language, avoid superlatives (“beautifully”, “perfectly”, “amazing”) - Humor expected (absurdity, self-deprecation, dry wit) - Formality level: Software Doug, Bruce Schneier, Elvin Yung tone - Canadian spellings (colour, centre) - No corporate jargon, buzzwords, or tired metaphors

Forbidden Words/Phrases: - Superlatives: amazing, incredible, game-changing, beautifully, perfectly - Corporate jargon: circle back, touch base, deep dive, leverage, synergy - Tech buzzwords: disruptive, innovative, cutting-edge, paradigm shift

Editorial Process (working/editorial-checklist.md): - Four required quality tests before publication: - Boss test: Former colleagues would see content as fair - Recruiter test: Shows value in 60 seconds of skimming - Doug test: Addresses real problem, not generic content - Peer test: Another SE would respect technical depth - Strong emphasis on originality and avoiding conventional wisdom repetition - Focus on analytical rigor over inspirational takeaways

Obsidian Integration

The repository is configured as an Obsidian vault: - .obsidian/ - Obsidian configuration - Plugin: qmd-as-md-obsidian for treating QMD files as Markdown in Obsidian - Allows for note-taking and content development within Obsidian

Content Guidelines for Code Assistance

When helping with content:

  1. Respect the voice - Analytical, show-don’t-tell, acknowledges complexity and limitations
  2. No superlatives - Avoid words like “beautifully”, “perfectly”, “amazing”
  3. Show through specifics - Use concrete examples, not abstract claims
  4. Canadian spellings - Use “colour”, “centre”, etc.
  5. Technical depth without exhaustion - Prove competence, trust reader expertise
  6. Failure analysis over lessons learned - Forensic analysis, not forced takeaways
  7. Plain language - Avoid jargon, buzzwords, corporate speak

Git Workflow Notes

Current branch: dev

The repository tracks both published content and working drafts. When committing: - Published content (*.qmd in root/cases/blog) should be ready for public viewing - Working directory changes are iterative and may be incomplete - Rendered output in docs/ directory is committed for GitHub Pages hosting

Technical Architecture Notes

  • Quarto generates static HTML from QMD (Quarto Markdown) files
  • No build step beyond quarto render
  • Site configuration lives entirely in _quarto.yml
  • Navigation structure defined via book chapters, not file system discovery
  • Theme customization through _quarto.yml format options (currently using cosmo theme)
  • Search functionality enabled via Quarto’s built-in search