Welcome!

Everyone needs a place to store their notes... this is mine for what it's worth.

Red Hacker

This is attempt number 32,456 at having an online storage place for all my notes and cheatsheets... lets see how long this one lasts.

This index page will contain a bunch of links, as well as the instructions to build this site, along with anything else I think deserves to go here.

"Everybody has a plan until they get punched in the jaw" - Mike Tyson

Useful Links

Spinning Hacker Head

Building this Site

This site costs a very small amount of money to run, and it could be ran for free if I wasn't so prissy about having a custom domain name. The only actual cost is said domain, and the yearly rental, which comes in at a wallet shattering $12.50 a year. You just need to create two free accounts.

Pre-requisites:

Some form of computer with internet access
Valid email address

If you have those two things you can follow these instructions and you too can have a little notes site on the internet.

Step One: Own a Domain

Own a domain.

If you don't own a domain, don't worry about it skip to Step Two and skip over Step Six.

Step Two: Netlify

Get an account on netlify.com.

Step Three: Docker

Download and install Docker then build the following image:

FROM ubuntu:latest

RUN apt update && apt upgrade -y
RUN apt install python3-full python3-pip -y
RUN pip install mkdocs mkdocs-material Pygments mkdocs-awesome-nav mkdocs-awesome-pages-plugin --break-system-packages

EXPOSE 8000
WORKDIR /srv/docs
CMD ["mkdocs", "build"]

Using ubuntu as the base image is probably a bit much but I was lazy and couldn't be bothered remembering the commands , feel free to adjust the above to suit your own needs, that's the general gist of what we want to do.

Edit: I went ahead and made an alpine image, it's waaay smaller:

FROM alpine:latest

RUN apk add python3 py3-pip
RUN pip install mkdocs mkdocs-material Pygments mkdocs-awesome-nav mkdocs-awesome-pages-plugin --break-system-packages

WORKDIR /srv/docs
CMD ["mkdocs", "build"]

Build that, give it a decent name (I called mine mkdocs-ubuntu and mkdocs-alpine).

Now all you need to get started is a folder with the following contents:

.
    docs/
    mkdocs.yaml

Now run the Docker you just built with the following:

docker run --rm --volume="$PWD:/srv/docs:Z" mkdocs-alpine

Save it in a script so you can just call the script from the local directory.

#!/bin/bash
docker run --rm --volume="$PWD:/srv/docs:Z" mkdocs-alpine

Make sure to chmod it:

chmod +x localbuild.sh

Then you can just call ./localbuild.sh and your site folder will automagically generate for you.

To check everything is working we can hijack the Docker image with the following:

docker run -it -p 8000:8000 --rm --volume="$PWD:/srv/docs:Z" mkdocs-alpine /bin/sh

That'll spawn a shell inside the container, you should see all of your local files in there. We can run the mkdocs internal server to do a bit of local debugging and testing from here with the following command:

mkdocs serve -a 0.0.0.0:8000

Now if you browse to http://localhost:8000 you should see your shiny new website and if you make any changes and save them while the mkdocs server is running you'll see the changes reflected in the browser.

Step Four: Github abuse

Create a new github repo, give it a sensible name.

git init
git add .
git commit -m "some sensible message"
git remote add origin githubrepo
git push -u origin main

Check that's pushed properly, if so, we now have our pipeline setup.

Step Five: Publishing

Head to app.netlify.com, authorise it to use GitHub and point it at your new repo.

Netlify will give you a silly name like famous-donut-fef1c0.netlify.app (which is this site)

Step Six: Custom Domain

Go to your domain and add a new CNAME. If you're not sure how to do that your domain provider will likely have documentation, you're not getting that help here.

Make a quick brew while the domain propagates, then head back to app.netlify.com and head to "Domain management" and set your new CNAME as

Step Seven: Make docs

Go forth and make funky docs.

If you want it to look exactly like this then you'll need to steal my mkdocs.yaml file... so here you go.

site_name: "Your Site Name Here"

theme:
  name: material
  palette:
    scheme: slate
    primary: red
  features:
    - content.code.copy
    - content.code.select

    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default 
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

plugins:
  - search
  - awesome-pages

And now you should be able to make some pretty documentation.

Each time you make changes you just do the following:

./localbuild.sh
git add .
git commit -m "commit message"
git push -u origin main

Or if you're on Windows:

docker run --rm -v ${PWD}:/srv/docs/ mkdocs
git add .
git commit -m "commit message"
git push -u origin main

Netlify will pick up the changes to the GitHub repo, trigger the build process, and in a fairly short time (depending on how big your site is and how much changed) you'll be able to see it on whatever domain, either your own custom one, or one provided by Netlify.

Enjoy!