@@ -4,35 +4,42 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
44
55## Project Overview
66
7- Jekyll-based technical blog with PWA support, dark mode, and bilingual content (English/Chinese) . Live at https://jasonrobert.me .
7+ Minimal Jekyll blog with Cyberpunk Brutalism design . Live at https://jasonrobert.me .
88
99## Development Commands
1010
1111``` bash
1212# Install dependencies
1313bundle install
1414
15- # Compile Less to CSS (REQUIRED before any commit with CSS changes)
16- ./build.sh
17- # Windows: bash build.sh
18-
1915# Local development
2016bundle exec jekyll serve
2117
2218# Production build
2319bundle exec jekyll build
2420```
2521
26- ## Critical Rules
22+ ## Architecture
2723
28- ### CSS/Less Workflow
29- 1 . ** NEVER edit ` /css ` files directly** - edit ` /less ` files instead
30- 2 . ** ALWAYS run ` ./build.sh ` before committing CSS changes** - GitHub Actions does NOT compile Less
31- 3 . Entry point: ` less/calder-blog.less ` imports all modules
32- 4 . Output: ` css/calder-blog.css ` (dev) + ` css/calder-blog.min.css ` (prod)
24+ ### Directory Structure
25+ ```
26+ /
27+ ├── _config.yml # Site configuration
28+ ├── _layouts/ # Page templates (default, post, page)
29+ ├── _posts/ # Blog posts (YYYY-MM-DD-title.md)
30+ ├── css/style.css # Single CSS file (Cyberpunk Brutalism)
31+ ├── img/ # Images
32+ ├── index.html # Homepage
33+ ├── about.md # About page
34+ ├── archive.html # Post archive
35+ ├── blog.html # Blog listing with pagination
36+ └── 404.html # Error page
37+ ```
3338
34- ### Frontend Development
35- ** Invoke ` Skill(frontend-design) ` before any UI/CSS work** - this ensures design quality and avoids generic AI aesthetics.
39+ ### Design System
40+ - ** Colors** : Dark background (#0a0a0f), Cyan accent (#00ffff)
41+ - ** Typography** : Space Mono (display), IBM Plex Sans (body), JetBrains Mono (code)
42+ - ** Style** : Cyberpunk Brutalism - sharp corners, neon glows, grid backgrounds
3643
3744### Blog Posts
3845Posts must follow naming: ` _posts/YYYY-MM-DD-title.md `
@@ -43,76 +50,22 @@ Front matter template:
4350layout : post
4451title : " Post Title"
4552subtitle : " Optional subtitle"
46- description : " SEO meta description (150-160 chars) "
53+ description : " SEO meta description"
4754date : YYYY-MM-DD HH:MM:SS
4855author : " Calder"
49- header-img : " img/path/to/header.jpg"
50- catalog : true # Enables table of contents sidebar
51- multilingual : false # Set true for posts with en.md/zh.md in _includes/posts/
5256tags :
53- - Tag1
57+ - Tag1
58+ - Tag2
5459---
5560```
5661
57- For FAQ structured data, use ` {% include faq-schema.html %} ` in posts.
58-
59- ## Architecture
60-
61- ### Key Directories
62- - ` less/ ` - Less source files (edit here for styles)
63- - ` _layouts/ ` - Page templates (default, post, page, keynote)
64- - ` _includes/ ` - Reusable components (nav, footer, head, faq-schema)
65- - ` js/ ` - Client scripts (dark-mode.js, search, PWA registration)
66-
67- ### Less Module Structure
68- ` calder-blog.less ` imports 19 modules in order:
69- 1 . ` variables.less ` - CSS custom properties, colors, breakpoints (768/992/1200px)
70- 2 . ` design-tokens.less ` - Spacing, typography scales
71- 3 . ` mixins.less ` - Reusable Less mixins
72- 4 . Component modules: sidebar, side-catalog, snackbar, highlight, search
73- 5 . Enhancement modules: tech, home, scroll, interactive, article, archive
74- 6 . ` dark-mode.less ` - Dark theme via ` [data-theme="dark"] ` selector
75- 7 . ` accessibility.less ` , ` multilingual.less ` , ` mobile-performance.less ` , ` editorial-design.less `
76-
77- Dark mode uses CSS custom properties toggled by ` js/dark-mode.js ` . Edit ` variables.less ` for both light and dark theme colors.
78-
79- ### Bilingual Content
80- Language-specific content lives in ` _includes/ ` subdirectories:
81- - ` _includes/about/en.md ` / ` zh.md ` - About page content
82- - ` _includes/posts/[date]-[slug]/en.md ` / ` zh.md ` - Post translations
83-
84- The multilingual selector component is in ` _includes/multilingual-sel.html ` .
85-
8662### Deployment
8763- Push to ` master ` triggers GitHub Actions deployment
8864- Workflow: ` .github/workflows/jekyll.yml `
8965- Ruby 3.1, auto-deploys to GitHub Pages
90- - Future-dated posts ARE published (` future: true ` in _ config.yml)
91-
92- ### PWA / Service Worker
93- ` sw.js ` implements offline-first caching with auto-versioning on each Jekyll build. Cache strategies:
94- - Pages: NetworkFirst (1hr cache)
95- - Static assets (JS/CSS): CacheFirst
96- - Images/fonts: Separate cache buckets
97-
98- Edit ` PRECACHE_LIST ` in ` sw.js ` to add critical offline resources.
99-
100- ## Common Issues
101-
102- ### Styles not updating after deploy
103- You forgot to run ` ./build.sh ` before commit. The compiled CSS files must be committed.
104-
105- ### Jekyll serve fails
106- Run ` bundle install ` first. Check Ruby version (needs 2.7+, prod uses 3.1).
107-
108- ### Dark mode not working
109- Check ` js/dark-mode.js ` and ` less/variables.less ` (both ` :root ` and ` [data-theme="dark"] ` blocks). Toggle via browser DevTools: ` document.documentElement.dataset.theme = 'dark' ` .
110-
111- ### Build script fails on Windows
112- Use WSL or Git Bash: ` bash build.sh `
66+ - Future-dated posts ARE published (` future: true ` )
11367
114- ## Key Configuration Files
68+ ## Key Configuration
11569
116- - ` _config.yml ` - Site metadata, SEO fields, social links, pagination, excluded paths
117- - ` pwa/manifest.json ` - PWA app manifest
118- - ` sw.js ` - Service worker (auto-versions via Jekyll)
70+ - ` _config.yml ` - Site metadata, social links, pagination
71+ - ` css/style.css ` - Complete design system (edit directly)
0 commit comments