Skip to content

Commit 904ac69

Browse files
mrbiggredmrbiggred
authored
Merge pull request #51 from weeklydevchat/feature/add-agent-files
Add agent files and updated readme
2 parents 389e637 + 227fa1f commit 904ac69

File tree

6 files changed

+550
-29
lines changed

6 files changed

+550
-29
lines changed

‎AGENTS.md‎

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

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2025 Weekly Dev Chat
3+
Copyright (c) 2025 Saturday Morning Productions Inc.
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

0 commit comments

Comments
 (0)