0xfab1.net
MkDocs
To honor this post (and ensure the message remains true) I will use my own website as an example and show how I configured the static web app and make it to work the way it does.
I am using Github Pages to host the content, Mkdocs to create the website from markdown files as input and have own domain for a nicer URL.
MkDocs is a great way to host a simple, static website. This website uses Material for MkDocs which is a theme for MkDocs.
To quickly create and host a static website (or rebuild this website), you have two choices:
- Docker
- Python
Docker
git clone https://github.com/FullByte/FullByte.github.io.git # clone repo
cd FullByte.github.io # Go to main folder
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/MkDocs-material # run the container
Python
Run this once to install all requirements:
choco install -y python
python -m pip install --upgrade pip
pip install MkDocs
pip install MkDocs-material
Run this in the folder of the MkDocs.yml file to host the MkDocs page:
mkdocs serve
Create page
If you do not like the default design of a theme or something is missing or extra that needs to be removed it is possible to overwrite template blocks: https://www.mkdocs.org/user-guide/customizing-your-theme/#using-the-theme-custom_dir.
I use method to add some files as well as overwrite a few things. It is generally more work as sometimes there are changes in mkdocs or material that force you to update your overrides as well. To see what I added to my "overrides" folder look here: https://github.com/FullByte/FullByte.github.io/tree/main/overrides
Extensions
MkDocs-material is a great theme and comes integrated with the pymkdown extensions, which lets you add tabbed code blocks, progress bars, task lists, keyboard symbols and more.
Further useful plugins:
- MkDocs-minify-plugin:
pip install MkDocs-minify-plugin
- MkDocs-redirects:
pip install MkDocs-redirects
Static Website Hosting Services
This website is hosted/built using the following services:
Service | Direct Link | 0xfab1 CNAME |
---|---|---|
GitHub Pages | 0xfab1@github | https://www.0xfab1.net/ |
IPFS with fleek | 0xfab1@IFPS | https://ipfs.0xfab1.net/ |
Netlify | 0xfab1@netlify | https://netlify.0xfab1.net |
Azure | Broke (my fault)... need to re-create this | https://azure.0xfab1.net |
Digital Ocean | 0xfab1@digitalocean | https://digitalocean.0xfab1.net |
Vercel | 0xfab1@vercel | https://vercel.0xfab1.net/ |
cloudflare | 0xfab1@cloudflare | https://cloudflare.0xfab1.net/ |
Render | 0xfab1@render | https://render.0xfab1.net |
AWS S3 | TODO | TODO |
Gitlab Pages | TODO | TODO |
I tried these services but they didn't suit me for my deployment at the time tested*:
- Heroku - php workaround breaks other builds
- edg.io - annoying DNS and build setup
- Fly.io - complicated build/requires extra files and github action changes
- Surge - complicated build/requires extra files and github action changes
- Firebase - complicated build/requires extra files and github action changes
- Feta - complicated build/requires extra files and github action changes
- Hostman - no free option
- Qovery - looks great but didn't get it to work for simple static websites
- Statically - great for one-pagers, not suitable for 0xfab1.net
- Linode - no free option
- koyeb - account closed for unknown reason
- Railway - worked fine until beginning of 2023 when the pricing model changed and the basic service was no longer free
*happy to learn from you how I can use them using a simple, automated deployment method for my static website :)
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 is based on this documentation:
name: mkdocs gh-deploy
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
name: Build and Deploy Documentation
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 dependencies
run: |
python -m pip install --upgrade pip
pip install mkdocs-material
- name: Deploy
run: |
git pull
mkdocs gh-deploy
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.