Skip to content

Commit 1827813

Browse files
author
[email protected]
committed
docs: add comprehensive GitHub Copilot instructions for 0xfab1.net project
1 parent 09b5fc9 commit 1827813

File tree

2 files changed

+317
-19
lines changed

2 files changed

+317
-19
lines changed

‎.copilot-instructions.md‎

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

‎docs/about/website/hosts.md‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,23 @@ I am trying out new services and if the host websites i try to run 0xfab1.net. H
66

77
This website is hosted/built using the following services:
88

9-
| Service | Direct Link | 0xfab1 CNAME |
10-
|----------------------------------------------------------|-----------------------------------------------------------------|-----------------------------------|
11-
| [GitHub Pages](https://pages.github.com/) | [0xfab1@github](https://fullbyte.github.io) | <https://www.0xfab1.net/> |
12-
| [IPFS](https://ipfs.io/) with [fleek](https://fleek.co/) | Broke (my fault)... need to re-create this | Broke (my fault)... need to re-create this |
13-
| [Netlify](https://www.netlify.com/) | [0xfab1@netlify](https://0xfab1.netlify.app/) | <https://netlify.0xfab1.net> |
14-
| [Azure](https://azure.microsoft.com) | Broke (my fault)... need to re-create this | Broke (my fault)... need to re-create this |
15-
| [Digital Ocean](https://m.do.co/c/0ef5c6b3f680) | [0xfab1@digitalocean](https://oxfab1-3l4ou.ondigitalocean.app/) | <https://digitalocean.0xfab1.net> |
16-
| [Vercel](https://vercel.com/) | [0xfab1@vercel](https://0xfab1.vercel.app/) | <https://vercel.0xfab1.net/> |
17-
| [cloudflare](https://www.cloudflare.com/) | [0xfab1@cloudflare](https://fullbyte-github-io.pages.dev) | <https://cloudflare.0xfab1.net/> |
18-
| [Render](https://render.com/) | [0xfab1@render](https://fullbyte-github-io.onrender.com/) | <https://render.0xfab1.net> |
19-
20-
Services to try:
21-
22-
- [AWS S3](https://aws.amazon.com/s3/)
23-
- [Gitlab Pages](https://about.gitlab.com)
24-
- [Surge](https://surge.sh/)
25-
26-
I tried these services but they didn't suit me for my deployment at the time tested*:
27-
9+
| Service | Direct Link | 0xfab1 CNAME |
10+
|----------------------------------------------------------|-----------------------------------------------------------------|--------------------------------------------|
11+
| [GitHub Pages](https://pages.github.com/) | [0xfab1@github](https://fullbyte.github.io) | <https://www.0xfab1.net/> |
12+
| [IPFS](https://ipfs.io/) with [fleek](https://fleek.co/) | Broke (my fault)... need to re-create this | Broke (my fault)... need to re-create this |
13+
| [Netlify](https://www.netlify.com/) | [0xfab1@netlify](https://0xfab1.netlify.app/) | <https://netlify.0xfab1.net> |
14+
| [Azure](https://azure.microsoft.com) | Broke (my fault)... need to re-create this | Broke (my fault)... need to re-create this |
15+
| [Digital Ocean](https://m.do.co/c/0ef5c6b3f680) | [0xfab1@digitalocean](https://oxfab1-3l4ou.ondigitalocean.app/) | <https://digitalocean.0xfab1.net> |
16+
| [Vercel](https://vercel.com/) | [0xfab1@vercel](https://0xfab1.vercel.app/) | <https://vercel.0xfab1.net/> |
17+
| [cloudflare](https://www.cloudflare.com/) | [0xfab1@cloudflare](https://fullbyte-github-io.pages.dev) | <https://cloudflare.0xfab1.net/> |
18+
| [Render](https://render.com/) | [0xfab1@render](https://fullbyte-github-io.onrender.com/) | <https://render.0xfab1.net> |
19+
| [Sevalla](https://app.sevalla.com/) | [0xfab1@kinsta](https://xfab1net-t93nk.kinsta.page/) | <https://sevalla.0xfab1.net> |
20+
21+
Services to try (again):
22+
23+
- [AWS S3](https://aws.amazon.com/s3/) - not tried yet
24+
- [Gitlab Pages](https://about.gitlab.com) - not tried yet, need to mirror repo first
25+
- [Surge](https://surge.sh/) - Automation broke at some point
2826
- [Heroku](https://www.heroku.com) - php workaround breaks other builds
2927
- [edg.io](https://edg.io/) - annoying DNS and build setup
3028
- [Fly.io](https://fly.io/) - complicated build/requires extra files and github action changes

0 commit comments

Comments
 (0)