Skip to content

Commit 809f106

Browse files
author
0xfab1
committed
2 parents bdcf9c7 + 92e668a commit 809f106

File tree

1,272 files changed

+4064
-1004
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,272 files changed

+4064
-1004
lines changed

‎.copilot-instructions.md‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
# GitHub Copilot Instructions - 0xfab1.net
2+
3+
This file provides instructions for GitHub Copilot when working on the 0xfab1.net MkDocs website project.
4+
5+
## Project Overview
6+
7+
**Type**: Static website built with MkDocs Material theme
8+
**Content**: 500+ markdown files covering tech documentation, tutorials, and personal content
9+
**Deployment**: GitHub Pages with automated CI/CD
10+
**Domain**: https://0xfab1.net
11+
12+
## Project Structure
13+
14+
```
15+
├── docs/ # All markdown content (EDIT THESE)
16+
│ ├── about/ # Personal and site information
17+
│ ├── tech/ # Technical documentation
18+
│ ├── make/ # Making/building guides
19+
│ └── index.md # Homepage
20+
├── site/ # Generated static site (⚠️ NEVER EDIT - AUTO-GENERATED!)
21+
├── overrides/ # MkDocs theme customizations (EDIT THESE)
22+
├── .github/workflows/ # CI/CD automation
23+
├── dockerfile # Multi-stage Docker build
24+
├── site_manager.py # Unified build tool
25+
└── mkdocs.yml # MkDocs configuration
26+
```
27+
28+
## ⚠️ Critical File Structure Rules
29+
30+
**NEVER EDIT FILES IN `site/` DIRECTORY**
31+
- The `site/` folder contains generated HTML output from MkDocs
32+
- All changes will be lost when the site is rebuilt
33+
- Always edit source files in `docs/` or `overrides/` instead
34+
35+
**Edit These Locations:**
36+
- ✅ `docs/` - All markdown content and assets
37+
- ✅ `overrides/` - Theme customizations and templates
38+
- ✅ Root files - Configuration (mkdocs.yml, dockerfile, etc.)
39+
40+
**Never Edit These:**
41+
- ❌ `site/` - Generated HTML (rebuilt every time)
42+
- ❌ `.venv/` - Python virtual environment
43+
44+
## Key Technologies
45+
46+
- **Site Generator**: MkDocs with Material theme
47+
- **Content Format**: Markdown files with front matter
48+
- **Image Processing**: Automated JPG/PNG → WebP conversion
49+
- **Containerization**: Docker with nginx + Let's Encrypt
50+
- **CI/CD**: GitHub Actions for automated builds and deployment
51+
52+
## Development Environment
53+
54+
**Python Environment**: Always use the virtual environment in `.venv/`
55+
```bash
56+
# Windows PowerShell
57+
& ".\.venv\Scripts\Activate.ps1"
58+
59+
# Unix/macOS
60+
source .venv/bin/activate
61+
```
62+
63+
**Dependencies**: Install with `pip install -r requirements.txt`
64+
65+
## Build System
66+
67+
### Primary Tool: site_manager.py
68+
69+
The project uses a unified build tool (`site_manager.py`) that handles:
70+
- Image optimization (JPG/PNG → WebP conversion)
71+
- Site statistics generation
72+
- MkDocs building and serving
73+
- Media path validation
74+
- Site testing
75+
76+
### Common Commands
77+
78+
```bash
79+
# Development server
80+
python site_manager.py serve
81+
82+
# Full build (includes image optimization)
83+
python site_manager.py build
84+
85+
# Image optimization only
86+
python site_manager.py optimize --mode all
87+
88+
# Generate site statistics
89+
python site_manager.py stats
90+
91+
# Test built site for issues
92+
python site_manager.py test
93+
94+
# Check media file references
95+
python site_manager.py check
96+
97+
# Clean build artifacts
98+
python site_manager.py clean
99+
```
100+
101+
### Build Options
102+
103+
- `--quiet`: Suppress verbose output (available for build command)
104+
- `--clean`: Clean build (removes previous artifacts)
105+
- `--no-optimize`: Skip image optimization during build
106+
- `--mode`: Image optimization mode (convert, update, cleanup, all)
107+
108+
## Content Guidelines
109+
110+
### File Organization
111+
- Place images in the same directory as the referencing markdown file
112+
- Use `_filename.ext` naming convention for assets
113+
- Keep related content together in logical directory structures
114+
115+
### Image Handling
116+
- **Preferred formats**: WebP (auto-converted), SVG for graphics
117+
- **Automatic processing**: JPG/PNG files are converted to WebP during build
118+
- **Preservation**: Animated GIFs preserved, SVG originals kept alongside WebP
119+
- **References**: Markdown image references are automatically updated to WebP
120+
121+
### Content Structure
122+
```markdown
123+
# Page Title
124+
125+
Brief description or introduction.
126+
127+
## Section Heading
128+
129+
Content with proper markdown formatting.
130+
131+
### Subsection
132+
133+
- Use consistent heading hierarchy
134+
- Include alt text for images: `![Description](image.webp)`
135+
- Use relative paths for internal links
136+
```
137+
138+
## Docker Configuration
139+
140+
### Multi-stage Build
141+
1. **Builder stage**: Python-based, runs image optimization and MkDocs build
142+
2. **Runtime stage**: nginx:alpine with Let's Encrypt integration
143+
144+
### Key Files
145+
- `dockerfile`: Production build configuration
146+
- `entrypoint.sh`: SSL certificate management and nginx startup
147+
- `nginx.conf`: Web server configuration
148+
149+
### Build Commands
150+
```bash
151+
# Local development
152+
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
153+
154+
# Production build
155+
docker build -t 0xfab1-site .
156+
docker run -d -p 80:80 -p 443:443 -v letsencrypt:/etc/letsencrypt 0xfab1-site
157+
```
158+
159+
## CI/CD Workflows
160+
161+
### build-0xfab1.yml
162+
- Triggers: Push to main, PRs, manual dispatch
163+
- Process: Install dependencies → Optimize images → Deploy to GitHub Pages
164+
- Key step: `python site_manager.py optimize --mode all --quiet`
165+
166+
### publish-dockerhub.yml
167+
- Triggers: Push to main, PRs, manual dispatch
168+
- Process: Multi-platform Docker build and push to Docker Hub
169+
- Uses: docker/build-push-action for efficient builds
170+
171+
## Performance Optimizations
172+
173+
### Build Optimizations
174+
- **Image conversion**: 55.2% size reduction (76MB → 34MB)
175+
- **Incremental processing**: Only converts new/modified images
176+
- **Docker caching**: Multi-stage builds with efficient layer caching
177+
- **Plugin management**: Heavy plugins disabled for development speed
178+
179+
### Runtime Optimizations
180+
- **Compression**: Gzip and Brotli in nginx
181+
- **HTTP/2**: Server push for critical resources
182+
- **Caching**: Browser caching headers
183+
- **CDN**: GitHub Pages CDN distribution
184+
185+
## Configuration Files
186+
187+
### mkdocs.yml
188+
- **Theme**: Material with dark/light mode
189+
- **Features**: Instant navigation, search highlighting, code blocks
190+
- **Plugins**: Search, minify, selective RSS (disabled for speed)
191+
- **Navigation**: Collapsed by default, use_directory_urls: false
192+
193+
### Requirements
194+
- Core: mkdocs, mkdocs-material
195+
- Optimization: pillow (image processing), cairosvg (SVG support)
196+
- Plugins: minify, rss, git-revision-date-localized, htmlproofer
197+
198+
## Development Workflow
199+
200+
### Making Changes
201+
1. **Content updates**: Edit markdown files in `docs/`
202+
2. **New images**: Place in same directory, let build process convert to WebP
203+
3. **Testing**: Run `python site_manager.py serve` for live preview
204+
4. **Validation**: Use `python site_manager.py test` and `python site_manager.py check`
205+
206+
### Before Committing
207+
1. Run image optimization: `python site_manager.py optimize --mode all`
208+
2. Test build: `python site_manager.py build`
209+
3. Check for issues: `python site_manager.py test`
210+
4. Verify media paths: `python site_manager.py check`
211+
212+
### Commit Guidelines
213+
```
214+
<type>: <description>
215+
216+
Types: feat, fix, docs, style, refactor, perf, test, chore
217+
Examples:
218+
- docs: add new ansible tutorial
219+
- feat: improve image optimization pipeline
220+
- fix: resolve broken audio file paths
221+
```
222+
223+
## Troubleshooting
224+
225+
### Common Issues
226+
- **Build failures**: Check Python environment activation
227+
- **Missing images**: Verify relative paths and file extensions
228+
- **Slow builds**: Use `--no-optimize` for development iterations
229+
- **Docker issues**: Ensure all referenced files exist in build context
230+
231+
### Performance Issues
232+
- **Large repo**: 449+ markdown files, expect 1-2 minute builds
233+
- **Image processing**: Can take time on first run, incremental after
234+
- **Plugin overhead**: Some plugins disabled for development speed
235+
236+
### Debug Commands
237+
```bash
238+
# Check site structure
239+
python site_manager.py stats
240+
241+
# Validate all media references
242+
python site_manager.py check
243+
244+
# Test built site for broken links
245+
python site_manager.py test
246+
247+
# Clean and rebuild
248+
python site_manager.py clean
249+
python site_manager.py build
250+
```
251+
252+
## Security Considerations
253+
254+
- **Content**: No sensitive data in markdown files or assets
255+
- **Images**: Strip EXIF metadata during WebP conversion
256+
- **Dependencies**: Keep MkDocs and plugins updated
257+
- **SSL/TLS**: Automated certificate management via Let's Encrypt
258+
259+
## Primary AI Assistant Role
260+
261+
**Main Objective**: Content quality assurance through fact-checking, spell-checking, and grammar correction.
262+
263+
### Content Review Priorities
264+
265+
1. **Fact-checking**: Verify technical accuracy, commands, URLs, and references
266+
2. **Spelling**: Identify and correct misspelled words throughout markdown content
267+
3. **Grammar**: Improve sentence structure, punctuation, and readability
268+
4. **Consistency**: Ensure terminology and formatting consistency across documents
269+
5. **Clarity**: Suggest improvements for unclear or ambiguous content
270+
271+
### Quality Assurance Workflow
272+
273+
```bash
274+
# Before reviewing content, activate environment
275+
& ".\.venv\Scripts\Activate.ps1"
276+
277+
# Generate current statistics for context
278+
python site_manager.py stats
279+
280+
# Check for broken links and media references
281+
python site_manager.py check
282+
283+
# Test site after content changes
284+
python site_manager.py test
285+
```
286+
287+
## AI Assistant Guidelines
288+
289+
When working on this project:
290+
291+
### Content Quality (Primary Focus)
292+
1. **Proofread all markdown content** for spelling, grammar, and clarity
293+
2. **Verify technical accuracy** of commands, code snippets, and procedures
294+
3. **Check external links** and references for validity and relevance
295+
4. **Ensure consistent terminology** across all documentation
296+
5. **Improve readability** through better sentence structure and organization
297+
298+
### ⚠️ CRITICAL: File Editing Rules
299+
6. **NEVER edit files in `site/` directory** - it contains auto-generated HTML that gets overwritten
300+
7. **Only edit source files**: `docs/` (content), `overrides/` (templates), root config files
301+
8. **Always verify file location** before editing - ensure it's NOT in the `site/` folder
302+
303+
### Technical Guidelines
304+
9. **Always activate the Python virtual environment** before running commands
305+
10. **Use site_manager.py** instead of direct mkdocs commands for consistency
306+
11. **Place images in the same directory** as the referencing markdown file
307+
12. **Use relative paths** for all internal references
308+
13. **Test changes locally** before suggesting CI modifications
309+
14. **Consider build performance** when adding new content or features
310+
15. **Follow existing directory structure** and naming conventions
311+
16. **Update statistics** after significant content changes
312+
17. **Validate media paths** when adding or moving files
313+
18. **Use WebP format** for new images when possible
314+
315+
## External References
316+
317+
- **MkDocs Documentation**: https://www.mkdocs.org/
318+
- **Material Theme**: https://squidfunk.github.io/mkdocs-material/
319+
- **GitHub Pages**: https://pages.github.com/
320+
- **Docker Hub**: https://hub.docker.com/r/0xfab1/0xfab1.net
321+
- **Live Site**: https://0xfab1.net

‎.cursor/environment.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"build": {
3+
"dockerfile": "Dockerfile",
4+
"context": "."
5+
},
6+
"terminals": []
7+
}

‎.cursor/rules/content-authoring.mdc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
description: "Rules and guidelines for creating and managing content (Markdown files) in the `docs/` directory."
3+
globs:
4+
- "docs/**/*.md"
5+
alwaysApply: false
6+
---
7+
8+
### Content Management (for `docs/**/*.md` files)
9+
10+
- New articles are created as `.md` files within the appropriate subdirectories of `docs/`.
11+
- When adding images, place them in the same directory as the article or a subdirectory. Reference them with relative paths.
12+
- The `image_optimizer.py` script will automatically process and optimize any new images during the build process.
13+
- Before committing, it's good practice to run `python check_media_paths.py` to find broken image or media links.

‎.cursor/rules/general.mdc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
description: "General context about this MkDocs project, including technology stack and local development commands."
3+
alwaysApply: true
4+
---
5+
6+
### General Project Context (MkDocs Blog)
7+
8+
- This is a personal blog built with the static site generator [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
9+
- The main configuration is in `mkdocs.yml`.
10+
- All content is located in the `docs/` directory as Markdown files.
11+
- Custom theme overrides are in the `overrides/` directory.
12+
- The project uses several Python scripts in the root for automation (building, image optimization, stats).
13+
14+
### Local Development Commands
15+
16+
- **To build the site:** Run `python build.py`. This script also optimizes images and generates stats.
17+
- **To serve the site locally:** Run `python serve.py`. The site will be available at `http://127.0.0.1:8000`. A quicker alternative is `python build.py --serve`.
18+
- **To do a quick build without optimization:** Run `python build.py --no-optimize`.

‎.cursor/rules/mkdocs-config.mdc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
description: "Instructions for editing the main `mkdocs.yml` configuration file."
3+
globs:
4+
- "mkdocs.yml"
5+
alwaysApply: false
6+
---
7+
8+
### MkDocs Configuration (`mkdocs.yml`)
9+
10+
- This is the central configuration file for the MkDocs site.
11+
- It defines the site name, theme, navigation, plugins, and markdown extensions.
12+
- When adding new plugins or changing the site structure, this file must be edited.

‎.cursor/rules/python-scripts.mdc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
description: "Overview of the Python helper scripts used in this project for automation."
3+
globs:
4+
- "*.py"
5+
alwaysApply: false
6+
---
7+
8+
### Python Scripts Overview
9+
10+
- `build.py`: Main script to build the entire site. It orchestrates other scripts like the image optimizer and stats generator.
11+
- `serve.py`: Starts a robust local development server with live reloading.
12+
- `image_optimizer.py`: Optimizes all images in the `docs` directory to reduce file size and improve website load times.
13+
- `generate_stats.py`: Creates various statistics about the site content.
14+
- `check_media_paths.py`: A utility script to validate that all media paths in Markdown files are correct.
15+
- `site_crawler.py` & `site_tester.py`: Scripts for testing the built site for broken links and other issues.

0 commit comments

Comments
 (0)