CLAUDE.md — AI Assistant Guide for maddenmanel.github.io

Project Overview

This is a personal technical blog by Madden Zhang (zhangxuegang@gmail.com), a software architect with 13+ years of experience. The site is built with Jekyll using the Minimal Mistakes remote theme and is hosted on GitHub Pages.

Live site: https://maddenmanel.github.io/

Repository Structure

.
├── _config.yml            # Jekyll site configuration (theme, plugins, author, defaults)
├── _data/
│   └── navigation.yml     # Top navigation menu links
├── _pages/                # Static pages (about, archives, 404)
│   ├── about.md
│   ├── 404.md
│   ├── category-archive.md
│   ├── tag-archive.md
│   └── year-archive.md
├── _posts/                # Blog posts (Markdown, YYYY-MM-DD-title.md naming)
├── assets/
│   └── images/            # Post images, organized by post name subdirectories
├── _site/                 # Generated output — DO NOT EDIT (auto-generated by Jekyll)
├── index.html             # Home page (uses "home" layout with pagination)
├── Gemfile                # Ruby gem dependencies
├── Gemfile.lock           # Locked gem versions
└── README.md              # Basic setup reference (from Minimal Mistakes template)

Technology Stack

Active Jekyll Plugins

• jekyll-paginate — post pagination (5 per page)
• jekyll-sitemap — auto-generate sitemap.xml
• jekyll-gist — embed GitHub gists
• jekyll-feed — RSS feed at /feed.xml
• jemoji — emoji support
• jekyll-include-cache — performance optimization
• jekyll-toc — table of contents generation

Development Workflow

Local Development

# Install dependencies (first time)
bundle install

# Serve locally with live reload
bundle exec jekyll serve

# Build static site only
bundle exec jekyll build

The site will be available at http://localhost:4000.

Note: _config.yml changes require a server restart. Live reload does NOT pick up config changes automatically.

Deployment

Push to the main branch — GitHub Pages automatically builds and deploys the Jekyll site. No CI/CD configuration is needed; GitHub Pages handles this natively.

Active development branch: claude/add-claude-documentation-O6dYs

Writing Blog Posts

File Naming Convention

Posts live in _posts/ and must follow this exact format:

YYYY-MM-DD-slug-with-hyphens.md

Examples:

• 2025-03-22-auto-pick-tool.md
• 2025-01-11-stability-monitor-prometheus.md

Important: Avoid spaces in filenames. The file 2025-03-31-mcp-intro-and -use.md has a space before -use — this is a naming error to avoid repeating.

Required Front Matter

Every post must start with a YAML front matter block:

---
title: "Post Title Here"
toc: true
excerpt_separator: "<!--more-->"
categories:
  - Blog
tags:
  - tag-one
  - tag-two
---

Optional Front Matter Fields

mathjax: true          # Enable LaTeX math rendering
excerpt: "Custom excerpt text"
header:
  image: /assets/images/post-name/header.jpg
  teaser: /assets/images/post-name/teaser.jpg

Default Behaviors (set in _config.yml)

All posts automatically get these settings — no need to repeat in front matter:

• layout: single
• author_profile: true
• read_time: true
• comments: true
• share: true
• related: true

Excerpt Separator

Use <!--more--> in the post body to control where the excerpt cuts off on the listing page.

Categories and Tags

• Categories determine the URL path: /:categories/:title/
• The site uses Blog as the primary category
• Tags are used for archive pages and discovery

Adding Images

Store images in assets/images/ under a subdirectory named after the post:

assets/images/2025-03-22-auto-pick-tool/1.png

Reference in Markdown:

![Alt text](/assets/images/2025-03-22-auto-pick-tool/1.png)

Navigation

Edit _data/navigation.yml to update the top navigation bar. Current links:

• Posts (/posts/)
• Categories (/categories/)
• Tags (/tags/)
• About (/about/)

Site Configuration (_config.yml)

Key settings to be aware of when modifying:

Content Topics

The blog covers technical architecture content. Existing post categories:

• Distributed Systems: Kafka, MySQL, Redis, ClickHouse
• Observability/Monitoring: Prometheus, Grafana, Jaeger, Loki, Promtail, Alertmanager
• DevOps/CI-CD: GitLab, Jenkins
• AI/ML: RAG agents, MCP (Model Context Protocol)
• Architecture: Clean Architecture, rule engines, payment systems
• Tools: Browser plugins, development tools

Key Conventions for AI Assistants

1. Never edit _site/ — it is generated output and will be overwritten on the next build.

2. Post filenames must not contain spaces — use hyphens only (e.g., my-post-title.md).

3. Front matter is required on every post and page — missing title or layout will break rendering.

4. Images go in assets/images/<post-slug>/ — keep images organized by post to avoid clutter.

5. Do not modify Gemfile.lock manually — let Bundler manage it via bundle update.

6. _config.yml is global — changes affect the entire site. Test locally before pushing.

7. The theme is a remote theme (mmistakes/minimal-mistakes) — theme files are not in this repo. Theme customization requires using Jekyll’s override mechanism (e.g., _layouts/, _includes/, _sass/ directories).

8. No test suite exists — manually verify by running bundle exec jekyll serve and checking the output in the browser.

9. Branch strategy: Develop on feature branches, merge to main for deployment.

10. Markdown flavor: GFM (GitHub Flavored Markdown) — tables, fenced code blocks, and task lists are supported.

Common Tasks

Add a new blog post

1. Create _posts/YYYY-MM-DD-post-slug.md
2. Add required front matter (title, toc, excerpt_separator, categories, tags)
3. Write content in Markdown
4. Add images to assets/images/YYYY-MM-DD-post-slug/ if needed
5. Commit and push to trigger GitHub Pages build

Update navigation

Edit _data/navigation.yml — changes are reflected immediately on next build.

Change author info

Edit the author: section in _config.yml.

Add a new static page

Create a .md file in _pages/ with front matter including permalink:.