Skip to content

Commit 37f84dc

Browse files
claudeclaude
committed
Add CLAUDE.md with comprehensive codebase documentation for AI assistants
Documents repository structure, Jekyll/Chirpy conventions, development workflows, post creation guidelines, configuration reference, and key constraints to help AI assistants work effectively in this repo. https://claude.ai/code/session_01Nfbjr497RyUJTqFxh2VM8d
1 parent 53bf9e8 commit 37f84dc

1 file changed

Lines changed: 174 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# CLAUDE.md — AI Assistant Guide for akashtalole.github.io
2+
3+
## Repository Overview
4+
5+
Personal blog/portfolio for Akash Talole, built with **Jekyll** and the **Chirpy theme** (~7.5), hosted on **GitHub Pages** at `https://akashtalole.github.io`.
6+
7+
- **Content focus**: AI/ML topics (GenAI, Claude Code, GitHub Copilot, Agentic AI, SDLC)
8+
- **Deployment**: GitHub Actions builds the site and deploys to GitHub Pages on push to `main`/`master`
9+
10+
---
11+
12+
## Directory Structure
13+
14+
```
15+
.
16+
├── _config.yml # Main Jekyll + Chirpy configuration
17+
├── Gemfile # Ruby gem dependencies
18+
├── index.html # Homepage (minimal; Jekyll processes it)
19+
├── _posts/ # Blog posts: YYYY-MM-DD-slug.md
20+
├── _tabs/ # Navigation pages (about, archives, categories, tags)
21+
├── _data/ # YAML data files (contact.yml, share.yml)
22+
├── _plugins/ # Ruby plugins (posts-lastmod-hook.rb)
23+
├── assets/
24+
│ ├── img/ # Images (avatar.jpg, post images)
25+
│ └── lib/ # Git submodule: chirpy-static-assets (do not edit)
26+
├── tools/
27+
│ ├── run.sh # Local dev server
28+
│ └── test.sh # Build + HTML validation
29+
├── .github/workflows/ # GitHub Actions CI/CD (pages-deploy.yml)
30+
└── .devcontainer/ # Dev container config (Jekyll + zsh)
31+
```
32+
33+
---
34+
35+
## Development Workflows
36+
37+
### Setup
38+
39+
```bash
40+
bundle install # Install Ruby dependencies (first time or after Gemfile changes)
41+
```
42+
43+
### Local Development
44+
45+
```bash
46+
bash tools/run.sh # Serve at http://127.0.0.1:4000 with live reload
47+
bash tools/run.sh -H 0.0.0.0 # Bind to all interfaces (Docker/devcontainer)
48+
bash tools/run.sh -p # Production mode
49+
```
50+
51+
The VS Code task **"Run Jekyll Server"** (Ctrl+Shift+B) calls `tools/run.sh`.
52+
53+
### Build & Test
54+
55+
```bash
56+
bash tools/test.sh # Build to _site/ + run htmlproofer (HTML validation)
57+
```
58+
59+
Run this before pushing to catch broken internal links. The VS Code task **"Build Jekyll Site"** calls `tools/test.sh`.
60+
61+
### CI/CD
62+
63+
Pushing to `main` or `master` triggers `.github/workflows/pages-deploy.yml`:
64+
1. Builds with `bundle exec jekyll b`
65+
2. Validates HTML with `htmlproofer` (external links excluded)
66+
3. Deploys artifact to GitHub Pages
67+
68+
---
69+
70+
## Creating Blog Posts
71+
72+
### File Naming
73+
74+
Place files in `_posts/` using the convention: `YYYY-MM-DD-slug-with-hyphens.md`
75+
76+
Example: `_posts/2026-04-09-my-new-post.md`
77+
78+
### Required Front Matter
79+
80+
```yaml
81+
---
82+
layout: post
83+
title: "Post Title Here"
84+
date: 2026-04-09 10:00:00 +0530
85+
categories: [category1, category2]
86+
tags: [tag1, tag2]
87+
description: "Brief description for SEO and post previews."
88+
author: akashtalole
89+
---
90+
```
91+
92+
### Optional Front Matter
93+
94+
```yaml
95+
image:
96+
path: /assets/img/post-image.jpg
97+
alt: "Image description"
98+
pin: true # Pin post to top of home page
99+
math: true # Enable LaTeX math rendering
100+
mermaid: true # Enable Mermaid diagram rendering
101+
toc: false # Disable table of contents (enabled globally by default)
102+
comments: false # Disable comments for this post
103+
```
104+
105+
### Notes on `last_modified_at`
106+
107+
Do **not** set `last_modified_at` manually. The plugin `_plugins/posts-lastmod-hook.rb` reads Git history and sets it automatically for posts with more than one commit.
108+
109+
---
110+
111+
## Configuration Reference (`_config.yml`)
112+
113+
Key settings:
114+
115+
| Setting | Value | Notes |
116+
|---|---|---|
117+
| `url` | `https://akashtalole.github.io` | No trailing slash |
118+
| `timezone` | `Asia/Kolkata` | Use `+0530` in post dates |
119+
| `paginate` | `10` | Posts per page |
120+
| `toc` | `true` | TOC enabled globally for posts |
121+
| `permalink` | `/posts/:title/` | Post URL structure |
122+
| `pwa.enabled` | `true` | PWA + offline cache enabled |
123+
| `comments.provider` | *(empty)* | Comments disabled; set to `disqus`, `utterances`, or `giscus` to enable |
124+
125+
---
126+
127+
## Naming Conventions
128+
129+
| Item | Convention | Example |
130+
|---|---|---|
131+
| Blog posts | `YYYY-MM-DD-slug.md` | `2026-04-09-agent-skills.md` |
132+
| Categories/tags | lowercase, hyphen-separated | `ai`, `agent-skills` |
133+
| Images | lowercase, hyphen-separated | `avatar.jpg`, `post-header.png` |
134+
| Shell scripts | `.sh` | `run.sh`, `test.sh` |
135+
| YAML config | lowercase, snake_case | `_config.yml` |
136+
137+
---
138+
139+
## Key Constraints
140+
141+
1. **`assets/lib` is a Git submodule** pointing to `chirpy-static-assets`. Never edit files inside it directly; run `git submodule update --remote` to update it.
142+
143+
2. **`.nojekyll` is intentional**. GitHub Pages deploys the pre-built `_site/` artifact produced by CI — it does not re-run Jekyll on the source. Do not remove this file.
144+
145+
3. **Do not add custom theme overrides** (layouts, includes, SCSS) without first consulting the [Chirpy theme documentation](https://chirpy.cotes.page/). Most UI behavior is provided by the `jekyll-theme-chirpy` gem.
146+
147+
4. **Code style** is enforced by `.editorconfig`:
148+
- UTF-8 charset
149+
- 2-space indentation (all files)
150+
- LF line endings
151+
- Single quotes in JS/CSS; double quotes in YAML
152+
153+
5. **Navigation tabs** (`_tabs/archives.md`, `_tabs/categories.md`, `_tabs/tags.md`) are auto-generated by Jekyll/Chirpy. Only edit `_tabs/about.md` for personal content.
154+
155+
6. **Do not edit `_site/`**. It is the build output directory, git-ignored, and overwritten on every build.
156+
157+
7. **Avoid committing `Gemfile.lock`** — it is in `.gitignore`. Dependencies are resolved fresh in CI.
158+
159+
---
160+
161+
## Data Files
162+
163+
- `_data/contact.yml` — Sidebar social links (GitHub, Twitter, email, RSS). Add/remove entries here to modify the sidebar.
164+
- `_data/share.yml` — Post-footer sharing buttons (Twitter, Facebook, Telegram). Add platforms by uncommenting or adding entries.
165+
166+
---
167+
168+
## Testing Checklist Before Pushing
169+
170+
- [ ] `bash tools/test.sh` completes without errors
171+
- [ ] No broken internal links reported by `htmlproofer`
172+
- [ ] Post front matter includes all required fields
173+
- [ ] Post file name follows `YYYY-MM-DD-slug.md` convention
174+
- [ ] Images placed in `assets/img/` and referenced with absolute paths (e.g., `/assets/img/my-image.jpg`)

0 commit comments

Comments
 (0)