diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0317f65 --- /dev/null +++ b/CLAUDE.md @@ -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.*