Github
All code is hosted on github.
Github Pages
I created a repo named FullByte.github.io
(Replace "FullByte" with your github username). Enable github pages for this repo in settings page of the repo. You will by default have a page available at FullByte.github.io.
Custom Domain
Mkdocs specifically uses the branch "gh-pages" by default to build the static website that will be served.
I added a custom domain "0xfab1.net" and added a file in the main folder of my repo called CNAME with one line containing my domain "0xfab1.net".
I added the following IPv4 DNS records (dig 0xfab1.net +noall +answer -t A
):
0xfab1.net. 0 IN A 185.199.108.153
0xfab1.net. 0 IN A 185.199.109.153
0xfab1.net. 0 IN A 185.199.110.153
0xfab1.net. 0 IN A 185.199.111.153
as well as these IPv6 DNS records (dig 0xfab1.net +noall +answer -t AAAA
):
0xfab1.net. 0 IN AAAA 2606:50c0:8000::153
0xfab1.net. 0 IN AAAA 2606:50c0:8001::153
0xfab1.net. 0 IN AAAA 2606:50c0:8002::153
0xfab1.net. 0 IN AAAA 2606:50c0:8003::153
and a CNAME record for www.0xfab1.net (dig www.0xfab1.net +noall +answer -t CNAME
):
www.0xfab1.net. 0 IN CNAME fullbyte.github.io.
Github Actions
Every time I commit to main I want the page to re-build so that the page is up-to-date. I currently don't use branches but this could be a good method to commit changes that should not yet be published. Once ready to publish, create a pull request of your branch and merge it to main.
My github action to build the static webpage using mkdocs looks as follows and includes the latest optimizations:
name: Build and Deploy Website
on:
push:
branches: [main]
pull_request:
branches: [main]
release:
types: [published]
workflow_dispatch:
jobs:
build:
# cancels the deployment for the automatic merge push created when tagging a release
if: contains(github.ref, 'refs/tags') == false || github.event_name == 'release'
name: Build and Deploy Website
runs-on: ubuntu-latest
steps:
- name: Checkout main
uses: actions/checkout@v2
- name: Set up Python 3.10
uses: actions/setup-python@v2
with:
python-version: '3.10'
- name: Install mkdocs dependencies
run: |
pip install --upgrade pip
pip install mkdocs-material
pip install mkdocs-minify-plugin
pip install mkdocs-rss-plugin
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-htmlproofer-plugin
pip install pillow
pip install cairosvg
- name: Optimize images
run: |
python image_optimizer.py --mode build
- name: Deploy Github Pages
env:
PYTHONWARNINGS: ignore
run: |
git pull
mkdocs gh-deploy --no-history 2>&1 | grep -v '\[git-revision-date-localized-plugin\]' | grep -v 'has no git logs' | grep -v 'First revision timestamp' | grep -v 'RSS-plugin.*Dates could not be retrieved' || true
There are many other nice things that could be done here. The main important part is to trigger the markdown to static website generator as github action on new commits so that the site is automatically built whenever you commit new content.
Build Tools
This website includes several automated build tools for enhanced development experience:
Local Development Scripts
Python Build Script (build.py
)
# Quick build with optimization
python build.py
# Build and start development server
python build.py --serve
# Skip image optimization (faster builds during development)
python build.py --no-optimize
# Clean build
python build.py --clean
PowerShell Build Script (build.ps1
)
# Quick build with optimization
.\build.ps1
# Build and serve on custom port
.\build.ps1 -Serve -Port 3000
# Skip optimization for faster development
.\build.ps1 -NoOptimize
Image Optimization Tool
The image_optimizer.py
script provides comprehensive image optimization:
# Automatic optimization during build
python image_optimizer.py --mode build
# Show current image inventory
python image_optimizer.py --inventory
# Manual optimization with clean references
python image_optimizer.py --mode all --clean-references
Features:
- Converts JPG/PNG to WebP automatically
- Updates markdown references to use WebP
- Preserves animated GIFs
- Handles SVG conversion with fallbacks
- 55.2% size reduction achieved
Current Statistics
Performance Metrics
- Total WebP Images: 544 optimized images
- Size Reduction: 55.2% (76MB → 34MB)
- Build Time: ~200 seconds (with full optimization)
- Preserved Files: 8 animated GIFs maintained for functionality
Technology Stack
- Static Site Generator: MkDocs with Material theme
- Image Optimization: Automated WebP conversion pipeline
- Compression: Gzip/Brotli support
- PWA Features: Service worker, offline functionality
- Security: CSP headers, HSTS, secure defaults
- CI/CD: GitHub Actions with automated deployment
- Hosting: Multi-platform deployment (GitHub Pages, Netlify, Vercel, etc.)
The website is fully optimized for performance, accessibility, and maintainability with automated workflows for content updates and image optimization.