CLAUDE.md

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

Architecture Overview

This is a Hugo static site for the Foss Cat blog (fosscat.com), using the Gokarna theme. The site includes blog posts, TILs (Today I Learned), and project pages.

Key architectural components:

Hugo framework: Static site generator with content in Markdown
Gokarna theme: Git submodule theme providing the site's design
Content structure: Posts in content/posts/, TILs in content/tils/, projects in content/projects/
Static assets: Images and other assets in static/ directory
Custom layouts: Overrides in layouts/ for TILs and other content types
Configuration: Main site config in config.toml

Development Commands

Environment Setup

# Initialize git submodules (theme)
git submodule init
git submodule update

# Enter Nix development environment (if using Nix)
nix develop

Building and Development

# Start development server with live reload
hugo server

# Build static site for production
hugo

# Build with drafts included
hugo --buildDrafts

Linting and Quality Checks

# Lint markdown files
markdownlint content/**/*.md

# Format markdown files
prettier --write content/**/*.md

# Spell check (requires aspell with English dictionary)
aspell check --mode=markdown --lang=en --personal=./.aspell.en.pws [filename.md]

Git Hooks

Pre-commit hooks automatically installed via scripts/install_hooks.sh
Hooks run markdown linting and spell checking on staged .md files
Personal dictionary in .aspell.en.pws for spell checking

Content Management

Creating New Content

# Create new blog post
hugo new posts/post-title.md

# Create new TIL
hugo new tils/til-title.md

# Create new project
hugo new projects/project-name.md

TILs (Today I Learned)

Custom archetype in archetypes/tils.md
Custom layouts in layouts/tils/ for list and single views
Accessible via /tils/ URL path

Site Configuration

Base URL: https://fosscat.com/
Theme: Gokarna (git submodule)
Syntax highlighting: catppuccin-frappe style
Content language: English (en-us)
Social icons: Configured for Gitea, Twitch, RSS
Navigation menu: Defined in config.toml

Development Environment

This repository uses Nix flakes for reproducible development environment including:

Hugo static site generator
Marksman (Markdown LSP)
Prettier (code formatter)
markdownlint-cli
aspell with English dictionaries

Quality Assurance

Markdown linting enforced via .markdownlint.jsonc configuration
Spell checking with personal dictionary support
Pre-commit hooks prevent commits with linting/spelling errors
Use git commit --no-verify to bypass hooks if needed

2.8 KiB Raw Blame History