Skip to content

Add comprehensive AI assistant guide (CLAUDE.md) #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
avinashahuja wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add comprehensive AI assistant guide (CLAUDE.md) #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
339 changes: 339 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,339 @@
# CLAUDE.md - AI Assistant Guide for avinashahuja.github.io

This document provides comprehensive guidance for AI assistants working with this codebase.

## Project Overview

**Project Type**: Personal blog and portfolio website
**Technology**: Jekyll static site generator with the Chirpy theme
**Deployment**: GitHub Pages with automated CI/CD via GitHub Actions
**URL**: https://avinashahuja.github.io
**License**: MIT

### Purpose
This is a personal blog built using Jekyll and the Chirpy theme, focusing on data science, machine learning, and career development topics. The site features a clean, responsive design with sidebar navigation and blog post listings.

## Repository Structure

```
.
├── _config.yml # Main Jekyll configuration file
├── _data/ # Data files for site configuration
│ ├── contact.yml # Contact information
│ ├── share.yml # Social sharing settings
│ └── locales/ # Internationalization files
├── _plugins/ # Jekyll plugins
│ └── posts-lastmod-hook.rb # Post last modified date plugin
├── _posts/ # Blog posts (markdown files)
├── _tabs/ # Static pages for navigation tabs
│ ├── about-me.md # About page
│ ├── archives.md # Post archives
│ ├── categories.md # Category listing
│ └── tags.md # Tag listing
├── .github/
│ └── workflows/
│ └── pages-deploy.yml # GitHub Actions deployment workflow
├── tools/
│ └── deploy.sh # Deployment script
├── Gemfile # Ruby dependencies
├── index.html # Homepage layout
└── README.md # Project documentation
```

## Key Technologies and Dependencies

### Core Stack
- **Jekyll**: Static site generator (v4.x compatible)
- **Ruby**: 2.7+ (specified in GitHub Actions)
- **Bundler**: Ruby dependency management
- **Theme**: jekyll-theme-chirpy ~> 4.3.4

### Dependencies (from Gemfile)
- `jekyll-theme-chirpy` - Main theme
- `html-proofer` - HTML validation (test group)
- `webrick` - Ruby 3.0 compatibility
- `tzinfo` and `tzinfo-data` - Timezone support (Windows/JRuby)
- `wdm` - Performance booster for Windows

## Configuration Details

### Site Settings (_config.yml)

**Important Configuration Values:**
- **Title**: ahuja.xyz
- **Tagline**: My blog
- **Timezone**: America/Los_Angeles
- **Base URL**: '' (empty, not a project site)
- **Language**: en
- **Theme Mode**: light
- **Pagination**: 10 posts per page
- **TOC**: Enabled globally for posts
- **Comments**: Enabled via Disqus (currently disabled in config)

**Author/Owner Information:**
- GitHub: avinashahuja
- Twitter: avinashahuja
- LinkedIn: linkedin.com/in/avinashahuja

### Markdown Processing
- **Engine**: Kramdown
- **Syntax Highlighter**: Rouge
- Line numbers enabled for code blocks
- Starting line number: 1

### Collections
- **tabs**: Output enabled, sorted by order field

## Content Creation Guidelines

### Blog Posts

**Location**: `_posts/`
**Naming Convention**: `YYYY-MM-DD-title-with-hyphens.md`

**Required Front Matter:**
```yaml
---
title: Your Post Title
author: Avinash Ahuja
date: YYYY-MM-DD HH:MM:SS +0800
categories: [Primary Category, Subcategory]
tags: [tag1, tag2, tag3]
render_with_liquid: false # Disable Liquid processing if needed
---
```

**Example Post Structure:**
```markdown
---
title: From Civil Engineering to Data Science (1/X)
author: Avinash Ahuja
date: 2019-12-02 20:10:00 +0800
categories: [Blog, career]
tags: [data science, machine learning]
render_with_liquid: false
---

Your content here...
```

**Best Practices for Posts:**
1. Use descriptive, SEO-friendly titles
2. Include at least one category (max 2 levels)
3. Add relevant tags for discoverability
4. Use proper date format with timezone offset
5. Enable TOC for longer posts (default: enabled)
6. Include code blocks with language specification for syntax highlighting

### Tab Pages

**Location**: `_tabs/`
**Purpose**: Static navigation pages (About, Archives, Categories, Tags)

**Required Front Matter:**
```yaml
---
title: Page Title
icon: fas fa-icon-name # Font Awesome icon
order: N # Determines tab order (1-4)
---
```

**Existing Tabs:**
1. About Me (order: 4)
2. Archives (auto-generated listing)
3. Categories (auto-generated listing)
4. Tags (auto-generated listing)

## Development Workflow

### Local Development Setup

**Prerequisites:**
1. Ruby (2.7+)
2. RubyGems
3. Jekyll
4. Bundler

**Installation Steps:**
```bash
# Install dependencies
bundle install

# Serve locally
bundle exec jekyll serve

# Build site
bundle exec jekyll build
```

**Development Server:**
- Runs on http://localhost:4000 by default
- Auto-regenerates on file changes
- Draft posts can be shown with `--drafts` flag

### Git Workflow

**Branch Structure:**
- `main`: Production branch, triggers automatic deployment
- Feature branches: Use descriptive names with prefix (e.g., `claude/feature-name-session-id`)

**Deployment Process:**
1. Make changes on feature branch
2. Test locally with `bundle exec jekyll serve`
3. Commit with clear, descriptive messages
4. Push to remote branch
5. Create PR to main (if desired)
6. Merge triggers automatic GitHub Actions deployment

### GitHub Actions CI/CD

**Workflow**: `.github/workflows/pages-deploy.yml`

**Trigger**: Push to `main` branch (excluding .gitignore, README.md, LICENSE)

**Steps:**
1. Checkout repository (full history for lastmod tracking)
2. Setup Ruby 2.7 with bundler caching
3. Run deployment script (`tools/deploy.sh`)

**Deployment Target**: GitHub Pages

## Coding Conventions

### File Naming
- Posts: `YYYY-MM-DD-lowercase-with-hyphens.md`
- Tabs: `lowercase-with-hyphens.md`
- Data files: `lowercase.yml`

### YAML Style
- Use 2-space indentation
- Quote strings containing special characters
- Use `>-` for multi-line descriptions

### Markdown Style
- Use ATX-style headers (`#`, `##`, etc.)
- Fenced code blocks with language specification
- Proper semantic structure (h1 → h2 → h3)

### Front Matter Standards
- Always include required fields (title, author, date)
- Categories: max 2 levels, use array syntax
- Tags: lowercase, descriptive, array syntax
- Dates: Include timezone offset (+0800)

## Theme Customization

The site uses the **Chirpy** theme, which is installed as a Ruby gem. This means:

1. Core theme files are in the gem, not the repository
2. Customizations override theme defaults
3. Theme files location: `bundle info --path jekyll-theme-chirpy`

**Customizable Elements:**
- `_config.yml`: Site-wide settings
- `_data/`: Contact info, locales, sharing options
- `_plugins/`: Custom Jekyll plugins
- Assets: Custom CSS, JS, images (if added)

**Theme Features:**
- Responsive design
- Dark/light mode toggle
- Category and tag archives
- Syntax highlighting
- Table of contents
- Social sharing
- SEO optimization

## Common Tasks for AI Assistants

### Creating a New Blog Post

1. Create file in `_posts/` with format: `YYYY-MM-DD-title.md`
2. Add required front matter
3. Write content in Markdown
4. Test locally if possible
5. Commit and push to feature branch

### Updating Site Configuration

1. Modify `_config.yml`
2. Common updates: title, social links, timezone, theme_mode
3. Test changes locally (may require server restart)
4. Commit with descriptive message

### Adding/Updating Tab Pages

1. Edit files in `_tabs/`
2. Maintain front matter (title, icon, order)
3. Use Markdown for content
4. Ensure icon uses Font Awesome class names

### Troubleshooting Build Issues

1. Check GitHub Actions workflow status
2. Verify YAML syntax (front matter and config)
3. Ensure dependencies are up to date in Gemfile.lock
4. Check for Kramdown/Rouge syntax errors
5. Validate HTML with html-proofer (test suite)

## Important Notes for AI Assistants

### DO:
- ✅ Follow the established naming conventions for posts
- ✅ Include all required front matter fields
- ✅ Use proper date format with timezone
- ✅ Test locally when possible before committing
- ✅ Write clear, descriptive commit messages
- ✅ Preserve existing code style and conventions
- ✅ Update this CLAUDE.md file if workflows change

### DON'T:
- ❌ Modify theme gem files directly
- ❌ Change Ruby version without testing
- ❌ Remove required front matter fields
- ❌ Commit directly to main branch without permission
- ❌ Change the baseurl without good reason
- ❌ Break existing post permalinks (impacts SEO)
- ❌ Push sensitive data (API keys, personal info)

### Special Considerations:

1. **Permalinks**: Default format is `/posts/:title/` - changing this breaks existing links
2. **Timezone**: Consistently use America/Los_Angeles (+0800 offset in dates)
3. **SEO**: Title, description, and tags are important for discoverability
4. **Performance**: Keep image sizes reasonable, use appropriate formats
5. **Accessibility**: Use semantic HTML, alt text for images
6. **Liquid Processing**: Disable with `render_with_liquid: false` if post contains syntax that conflicts

## Testing Checklist

Before pushing changes:
- [ ] YAML front matter is valid
- [ ] Markdown renders correctly
- [ ] Links work and are not broken
- [ ] Code blocks have language specification
- [ ] Images load properly (if applicable)
- [ ] Post date is correct with timezone
- [ ] Categories and tags are lowercase and meaningful
- [ ] Local build succeeds without errors
- [ ] Commit message is clear and descriptive

## Resources

- **Chirpy Theme Documentation**: https://github.com/cotes2020/jekyll-theme-chirpy
- **Jekyll Documentation**: https://jekyllrb.com/docs/
- **Kramdown Syntax**: https://kramdown.gettalong.org/syntax.html
- **Font Awesome Icons**: https://fontawesome.com/icons
- **GitHub Pages**: https://docs.github.com/en/pages

## Maintenance Notes

**Last Updated**: 2025-11-18
**Jekyll Version**: 4.x compatible
**Theme Version**: ~> 4.3.4
**Ruby Version**: 2.7+ (GitHub Actions)

---

*This file should be updated whenever significant changes are made to the repository structure, build process, or conventions.*