Skip to content

CLAUDE.md

Latest commit

 

History

History
127 lines (84 loc) · 4.49 KB

CLAUDE.md

File metadata and controls

127 lines (84 loc) · 4.49 KB
Raw

CLAUDE.md

Take always into consideration the instructions in @AGENTS.md.

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

Project Overview

This is a minimalist personal website/blog for Jaime Gómez-Obregón. It's a static single-page application built with vanilla JavaScript, HTML, and CSS—no frameworks or external libraries. The project follows a philosophy of radical simplicity, technical excellence, and human-centered design.

Architecture

Content Model

The site has two content types defined in httpdocs/index.json (a JSON Feed):

  • Posts (/httpdocs/posts/): Articles with a date_published field, displayed chronologically
  • Pages (/httpdocs/pages/): Timeless content without publication dates

Each content item is a directory containing at minimum an index.html file with the article content. Additional resources (images, styles, etc.) live in the same directory. An optional poster.png is used for social media sharing.

Client-Side Routing

The application is a SPA with client-side routing:

  • httpdocs/modules/website.js - Main blog logic and routing
  • httpdocs/modules/strings.js - String utilities (HTML escaping, slugification)
  • httpdocs/modules/element.js - DOM utilities

Web Components:

  • httpdocs/components/initial.js - Decorative initial letters (William Morris style)
  • httpdocs/components/separator.js - Thematic separators

Build System

  • Development: yarn serve or npm run serve - Runs esbuild dev server with watch mode
  • Production: yarn build or npm run build - Bundles assets and generates static HTML with metadata

The build script (bin/build.sh):

  1. Copies httpdocs/ to build/
  2. Bundles and minifies JS/CSS with esbuild to build/assets/
  3. Generates individual HTML files for each post/page with proper metadata (OpenGraph, Twitter cards)
  4. Extracts metadata from index.json and injects it into each page's <head>

Deployment

Deploys to Netlify on push to master branch. Configuration in netlify.toml.

Key Features & Implementation Details

Content Management

To add new content:

  1. Create a directory in httpdocs/posts/ (for posts) or httpdocs/pages/ (for pages)
  2. Add index.html with content (must include an <h1> for the title)
  3. Add entry to httpdocs/index.json:
    • Include date_published for posts
    • Omit date_published for pages
    • Add "Destacado" to tags array to feature on homepage

Scheduled Posts

Posts with future date_published dates won't appear on the homepage until that date.

Typography Features

  • Em dashes: The code prevents orphaned em dashes (—) by inserting Unicode WORD JOINER (U+2060) characters
  • Decorative initials: First letter of paragraphs can be styled with William Morris SVG letters from /httpdocs/initials/
  • Roman numerals: Rendered in small caps per RAE recommendations

Embedded Content

  • Tweets: Use <blockquote class="tweet" data-id="[tweet_id]"></blockquote> - the Twitter widgets library loads dynamically
  • YouTube videos: Automatically resized to 16:9 aspect ratio
  • Footnotes: Use <a class="note" href="#note-id"> and <ol id="notes"> - automatically numbered and cross-linked

Linkable Sections

All <h2> elements are automatically converted to anchors for section linking.

Development Commands

# Install dependencies
yarn install
# or
npm install

# Start development server (esbuild with watch mode)
yarn serve
# or
npm run serve

# Build for production
yarn build
# or
npm run build

Code Style & Linting

The project uses:

  • Prettier: Configured with semi: false and singleQuote: true (see package.json)
  • Stylelint: For CSS linting (extends stylelint-config-standard and stylelint-config-recess-order)
  • EditorConfig: Enforces 2-space indentation, LF line endings, UTF-8, max line length 80

File Structure Notes

  • httpdocs/ - Source files served in development
  • build/ - Production output (gitignored, generated by build script)
  • httpdocs/tmp/ - Temporary file sharing directory (cleared on each deploy)
  • bin/build.js - Node.js build utilities
  • bin/build.sh - Main build script (Bash)
  • bin/serve.sh - Development server script

Important Constraints

  • No external JavaScript libraries or frameworks
  • No backend/database - purely static
  • No tracking cookies or analytics
  • Semantic HTML5 markup
  • All code must validate against W3C specifications
  • PageSpeed Insights score target: 97-100/100