Skip to content

Commit b9a2dfc

Browse files
mrbiggredmrbiggred
committed
Add AGENTS.md for project documentation and guidelines
1 parent 389e637 commit b9a2dfc

File tree

2 files changed

+388
-0
lines changed

2 files changed

+388
-0
lines changed

‎AGENTS.md‎

Lines changed: 387 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,387 @@
1+
# AGENTS.md
2+
3+
## Project Overview
4+
5+
This is the **Weekly Dev Chat** website, a static site built with MkDocs Material and hosted on GitHub Pages. The site serves as a platform for a weekly virtual developer chat community that meets every Tuesday at 12pm Mountain Time.
6+
7+
**Live Site**: https://weeklydevchat.github.io
8+
**Repository**: weeklydevchat/weeklydevchat.github.io
9+
**Main Branch**: `main`
10+
**Deployment**: Automated via GitHub Actions to `gh-pages` branch
11+
12+
## Technology Stack
13+
14+
- **Static Site Generator**: MkDocs
15+
- **Theme**: Material for MkDocs
16+
- **Language**: Python 3.x
17+
- **Hosting**: GitHub Pages
18+
- **CI/CD**: GitHub Actions
19+
- **Container Support**: Docker Compose
20+
21+
## Project Structure
22+
23+
```
24+
.
25+
├── mkdocs.yml # Main configuration file
26+
├── requirements.txt # Python dependencies (mkdocs-material)
27+
├── docker-compose.yml # Docker development environment
28+
├── docker-entrypoint.sh # Docker startup script
29+
├── create_post.sh # Bash script to create new blog posts
30+
├── create_post.ps1 # PowerShell script to create new blog posts
31+
├── .github/
32+
│ └── workflows/
33+
│ └── ci.yml # GitHub Actions deployment workflow
34+
└── docs/ # All site content
35+
├── .authors.yml # Author metadata (chris, norm, omar)
36+
├── index.md # Homepage
37+
├── join.md # How to join the chat
38+
├── past_topics.md # Archived topics (excluded from build)
39+
├── hosts/
40+
│ └── index.md # Current hosts page
41+
├── past-hosts/
42+
│ └── index.md # Past hosts page
43+
├── sponsors/
44+
│ └── index.md # Sponsors page
45+
├── posts/ # Blog posts organized by date
46+
│ └── YYYY/
47+
│ └── MM/
48+
│ └── DD/
49+
│ └── index.md # Blog post content
50+
├── assets/ # Images, logos, fonts, design files
51+
│ └── logo/ # Site branding assets
52+
└── stylesheets/
53+
└── extra.css # Custom CSS overrides
54+
```
55+
56+
## Key Configuration (mkdocs.yml)
57+
58+
### Site Information
59+
- **Site Name**: Weekly Dev Chat
60+
- **Site URL**: https://weeklydevchat.github.io
61+
- **Description**: Every Tuesday at 12pm Mountain Time
62+
63+
### Theme Configuration
64+
- **Theme**: Material for MkDocs
65+
- **Primary Color**: Teal
66+
- **Accent Color**: Blue
67+
- **Font**: Roboto
68+
- **Logo**: `assets/logo/png/square_logo_light_150.png`
69+
- **Favicon**: `assets/logo/Favicons/16X16_favicon2.png`
70+
- **Features**: Navigation indexes enabled
71+
72+
### Plugins
73+
1. **search**: Built-in search functionality
74+
2. **blog**: Enables blog functionality
75+
- Blog directory: Root (`.`)
76+
- Pagination: 3 posts per page
77+
78+
### Navigation Structure
79+
- Home (index.md)
80+
- Join (join.md)
81+
- Hosts (hosts/index.md)
82+
- Past Hosts (past-hosts/index.md)
83+
- Sponsors (sponsors/index.md)
84+
85+
### Markdown Extensions
86+
- `attr_list`: Allows specifying image dimensions and attributes
87+
88+
### Custom Styling
89+
- Custom CSS: `stylesheets/extra.css`
90+
- Responsive logo styling for articles
91+
92+
## Authors
93+
94+
Three hosts are configured in `docs/.authors.yml`:
95+
96+
1. **chris** - Chris Cumming (Host)
97+
2. **norm** - Norman Lorrain (Host)
98+
3. **omar** - Omar Ashour (Host)
99+
100+
Each author has a name, description, and avatar URL.
101+
102+
## Blog Post Conventions
103+
104+
### File Structure
105+
Blog posts are organized by date: `docs/posts/YYYY/MM/DD/index.md`
106+
107+
### Post Frontmatter
108+
```yaml
109+
---
110+
title: "Your Blog Post Title"
111+
date: YYYY-MM-DD
112+
authors:
113+
- chris | norm | omar # One or more authors
114+
---
115+
```
116+
117+
### Post Content Template
118+
```markdown
119+
TOPIC_INTRODUCTION_HERE
120+
121+
Everyone and anyone are welcome to [join](https://weeklydevchat.com/join/) as long as you are kind, supportive, and respectful of others. Zoom link will be posted at 12pm MDT.
122+
123+
![alt text](YYYY-MM-DD_image_filename.webp)
124+
```
125+
126+
### Creating New Posts
127+
128+
Two helper scripts are available for creating new blog posts:
129+
130+
1. **Bash Script** (`create_post.sh`):
131+
- Calculates next Tuesday from current date
132+
- Creates directory structure: `docs/posts/YYYY/MM/DD/`
133+
- Generates `index.md` with proper frontmatter template
134+
- Usage: `./create_post.sh`
135+
136+
2. **PowerShell Script** (`create_post.ps1`):
137+
- Same functionality as bash script
138+
- For Windows users
139+
- Usage: `.\create_post.ps1`
140+
141+
Both scripts automatically determine the date of the next Tuesday (or current day if Tuesday) and create the appropriate directory structure.
142+
143+
## Development Workflows
144+
145+
### Local Development (Native)
146+
147+
**Prerequisites**:
148+
- Python 3.x (recommend using virtual environment)
149+
- mkdocs-material package
150+
151+
**Setup**:
152+
```bash
153+
# Install dependencies
154+
pip install mkdocs-material
155+
156+
# Start development server with live reload
157+
mkdocs serve
158+
159+
# Site available at http://127.0.0.1:8000
160+
```
161+
162+
### Local Development (Docker)
163+
164+
**Prerequisites**:
165+
- Docker and Docker Compose
166+
167+
**Setup**:
168+
```bash
169+
# Start development server
170+
docker compose up app
171+
172+
# Site available at http://localhost:8000
173+
# Hot-reloading enabled for development
174+
```
175+
176+
### Testing Changes
177+
Before pushing changes, always test locally using `mkdocs serve` or Docker to verify:
178+
- Content renders correctly
179+
- Navigation works
180+
- Images load properly
181+
- Custom CSS applies as expected
182+
183+
## Deployment
184+
185+
### Automated Deployment (GitHub Actions)
186+
187+
**Trigger**: Push to `main` branch
188+
189+
**Workflow** (`.github/workflows/ci.yml`):
190+
1. Checks out repository
191+
2. Configures git credentials (github-actions bot)
192+
3. Sets up Python 3.x
193+
4. Caches mkdocs-material dependencies
194+
5. Installs mkdocs-material
195+
6. Runs `mkdocs gh-deploy --force`
196+
7. Deploys to `gh-pages` branch
197+
198+
**Permissions**: Requires `contents: write` permission
199+
200+
**Cache**: Weekly cache refresh based on week number
201+
202+
### Manual Deployment
203+
Not typically needed due to automated workflow, but can be done:
204+
```bash
205+
mkdocs gh-deploy --force
206+
```
207+
208+
## Git Ignore Patterns
209+
210+
The following are ignored:
211+
- `.venv/` - Python virtual environments
212+
- `site/` - MkDocs build output
213+
- `.DS_Store` - macOS metadata files
214+
215+
## Important Files to Modify
216+
217+
### For Content Changes
218+
- `docs/index.md` - Homepage content
219+
- `docs/join.md` - Join instructions
220+
- `docs/hosts/index.md` - Current hosts information
221+
- `docs/sponsors/index.md` - Sponsor information
222+
- `docs/posts/YYYY/MM/DD/index.md` - Blog posts
223+
224+
### For Configuration Changes
225+
- `mkdocs.yml` - Site configuration, theme, plugins, navigation
226+
- `docs/.authors.yml` - Author metadata
227+
- `docs/stylesheets/extra.css` - Custom styling
228+
229+
### For Assets
230+
- `docs/assets/logo/` - Logo files (PNG, SVG)
231+
- `docs/assets/logo/Favicons/` - Favicon files
232+
- `docs/posts/YYYY/MM/DD/` - Post-specific images
233+
234+
## Common Agent Tasks
235+
236+
### Creating a New Blog Post
237+
238+
1. **Determine the date**: Calculate next Tuesday or use provided date
239+
2. **Create directory**: `docs/posts/YYYY/MM/DD/`
240+
3. **Create index.md** with proper frontmatter:
241+
```yaml
242+
---
243+
title: "Topic Title"
244+
date: YYYY-MM-DD
245+
authors:
246+
- chris
247+
---
248+
```
249+
4. **Add content** following the template
250+
5. **Add image** if needed (typically named `YYYY-MM-DD_description.webp` or `.png`)
251+
6. **Test locally** before committing
252+
253+
### Modifying Site Configuration
254+
255+
1. **Edit mkdocs.yml** for:
256+
- Navigation changes
257+
- Theme settings
258+
- Plugin configuration
259+
- Markdown extensions
260+
2. **Test changes** with `mkdocs serve`
261+
3. **Verify** no build errors
262+
4. **Commit and push** to trigger deployment
263+
264+
### Adding a New Page
265+
266+
1. **Create markdown file** in `docs/` directory
267+
2. **Add to navigation** in `mkdocs.yml` under `nav:` section
268+
3. **Test locally** to verify navigation works
269+
4. **Commit changes**
270+
271+
### Updating Authors
272+
273+
1. **Edit** `docs/.authors.yml`
274+
2. **Add/modify** author entry:
275+
```yaml
276+
author_id:
277+
name: Full Name
278+
description: Role
279+
avatar: https://weeklydevchat.github.io/path/to/avatar.png
280+
```
281+
3. **Ensure avatar image** exists in the repository
282+
4. **Test** by creating a post with the new author
283+
284+
### Styling Changes
285+
286+
1. **Edit** `docs/stylesheets/extra.css`
287+
2. **Test** styling changes locally
288+
3. **Ensure responsive design** works (check mobile/desktop)
289+
4. **Commit changes**
290+
291+
## Excluded Content
292+
293+
- `docs/past_topics.md` is explicitly excluded from the build (see `exclude_docs` in mkdocs.yml)
294+
295+
## Important Notes for Agents
296+
297+
1. **Never modify** `.github/workflows/ci.yml` unless explicitly requested - deployment is automated and stable
298+
2. **Always test locally** before pushing changes to main branch
299+
3. **Blog posts must follow** the date-based directory structure: `YYYY/MM/DD/`
300+
4. **Frontmatter is required** for all blog posts (title, date, authors)
301+
5. **Images for blog posts** should be placed in the same directory as the post's `index.md`
302+
6. **The site uses** Material for MkDocs theme - refer to https://squidfunk.github.io/mkdocs-material/ for advanced features
303+
7. **Custom CSS** should be minimal and placed in `docs/stylesheets/extra.css`
304+
8. **Navigation order** is controlled by the `nav:` section in `mkdocs.yml`
305+
9. **The main branch** is protected - all pushes trigger automatic deployment
306+
10. **Posts use** the blog plugin's automatic listing - no manual index needed
307+
308+
## Useful Commands Reference
309+
310+
```bash
311+
# Development
312+
mkdocs serve # Start development server
313+
mkdocs serve -a 0.0.0.0:8000 # Start server accessible on network
314+
315+
# Build
316+
mkdocs build # Build static site to site/ directory
317+
mkdocs build --clean # Clean build
318+
319+
# Deployment
320+
mkdocs gh-deploy # Deploy to GitHub Pages
321+
mkdocs gh-deploy --force # Force deploy (used by CI)
322+
323+
# Help
324+
mkdocs -h # Show help
325+
326+
# Docker
327+
docker compose up app # Start development server in Docker
328+
docker compose down # Stop Docker containers
329+
330+
# Create new post
331+
./create_post.sh # Create post for next Tuesday (bash)
332+
.\create_post.ps1 # Create post for next Tuesday (PowerShell)
333+
```
334+
335+
## MkDocs Material Blog Plugin Details
336+
337+
The blog plugin is configured with:
338+
- **Blog directory**: Root (`.`) - blog appears on homepage
339+
- **Pagination**: 3 posts per page
340+
- **Posts directory**: `docs/posts/`
341+
- **Automatic post discovery**: Based on frontmatter date
342+
- **Archive pages**: Automatically generated
343+
- **Author integration**: Uses `docs/.authors.yml`
344+
345+
For more blog plugin features, see: https://squidfunk.github.io/mkdocs-material/plugins/blog/
346+
347+
## Troubleshooting
348+
349+
### Build Fails
350+
- Check YAML syntax in frontmatter
351+
- Verify all referenced images exist
352+
- Check mkdocs.yml for syntax errors
353+
- Review GitHub Actions logs
354+
355+
### Images Not Loading
356+
- Verify image path is relative to the markdown file
357+
- Check image file exists in correct location
358+
- Ensure image filename matches reference in markdown
359+
360+
### Navigation Issues
361+
- Verify file path in `mkdocs.yml` nav section matches actual file location
362+
- Check for typos in file paths
363+
- Ensure referenced files exist
364+
365+
### Styling Not Applied
366+
- Check `extra.css` syntax
367+
- Verify `extra_css` is configured in `mkdocs.yml`
368+
- Clear browser cache
369+
- Check if Material theme update changed CSS class names
370+
371+
## Resources
372+
373+
- **MkDocs Documentation**: https://www.mkdocs.org
374+
- **Material for MkDocs**: https://squidfunk.github.io/mkdocs-material/
375+
- **Blog Plugin**: https://squidfunk.github.io/mkdocs-material/plugins/blog/
376+
- **GitHub Pages**: https://docs.github.com/en/pages
377+
- **Site**: https://weeklydevchat.github.io
378+
379+
## Project Goals and Philosophy
380+
381+
This is a community-focused project for a weekly developer chat. Content should be:
382+
- Welcoming and inclusive
383+
- Focused on software development topics
384+
- Clear and accessible
385+
- Updated regularly (weekly posts for Tuesday chats)
386+
387+
Keep the site simple, maintainable, and focused on content over complexity.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

0 commit comments

Comments
 (0)