Skip to content

25/08/25 - Creating This Website

System Maintenance

  • Updated Zsh.
  • Ran system-wide package update (sudo pacman -Syu).

So today I want to figure out MkDocs and document my process of making these .md files into a legible GitHub Page.

MkDocs Project

  • Cleaned up the journal structure: instead of one giant file, I moved entries into 00-journal/ as individual dated files (YYYY-MM-DD.md).
    This will make the MkDocs site easier to generate and browse.
  • Set up the .github/workflows/gh-pages.yml workflow to automatically build with MkDocs and deploy to GitHub Pages.
  • Changed the repo remote from HTTPS to SSH so pushes no longer ask for tokens or crash the Git Credential Manager.
  • Verified that the site went live at odonnellrory.github.io, though currently it only displayed the README.

To Do:

  • Re-run the Actions job with the new permissions block and confirm the MkDocs site (with journal + hardware docs) actually renders.
  • If it still fails, capture the job logs to debug further.

Going out now so will continue this later.

Got MkDocs working! The missing link was telling GitHub Actions to actually build the MkDocs site instead of just serving my repo root.
I added the proper workflow that installs MkDocs, runs mkdocs build, and then uploads the site/ directory as the artifact for GitHub Pages.

Pushed to main, re-ran the workflow, and watched the Actions logs step through

checkout > MkDocs build > deploy

This time no git errors, and the deploy step completed successfully.

Verified at odonnellrory.github.io that the MkDocs Material theme is active, the navigation links work,
and my journal entries are browsable in a clean, dated structure.

To Do:

  • Automate journal navigation updates (so I don’t have to hand-edit mkdocs.yml for each new entry).
  • Look into plugins like mkdocs-awesome-pages-plugin to auto-sort by filename/date.
  • Decide on journal entry format (timestamps vs. no timestamps).
  • Hardware list.
  • Add a To-Do list page for tracking new tasks.
  • Implement images.
  • Install NixOS on the laptop.
  • Update README.md.
  • Set up local preview (mkdocs serve) to test changes live before pushing to GitHub.

How I Did It

  • I structured the repo as docs/00-journal/YYYY-MM-DD.md yesterday and decided to publish with MkDocs + GitHub Pages.
  • Made homelab the main site: I renamed the repo to odonnellrory.github.io so it serves at the root domain.
  • Switched Pages to GitHub Actions: In Settings > Pages I set the source to GitHub Actions, so GitHub serves whatever my workflow publishes.
ChatGPT's Explanation of the .yml file:

Understanding .github/workflows/gh-pages.yml

This file is a GitHub Actions workflow that automates building and publishing my MkDocs site to GitHub Pages.

  • name: Human-readable label that shows up in the Actions tab.

  • on: Defines the triggers.

  • push on the main branch > rebuild site every time I push.

  • workflow_dispatch > allows manual re-runs from the GitHub UI.

  • permissions: Explicitly grant the workflow the minimal rights it needs:

  • contents: read to pull source code,
  • pages: write to publish to Pages,

  • id-token: write for OIDC authentication.

  • concurrency: Ensures only one Pages build runs at a time (cancel-in-progress: true), so repeated pushes don’t overlap.

  • jobs > build:

  • runs-on: ubuntu-latest > this job runs inside GitHub’s own Ubuntu VM, not my local Arch machine. Hosted runners are standard for CI/CD.
  • Checkout: pulls the repo contents.
  • Setup Python: ensures a clean Python 3.11 environment.
  • Install MkDocs + theme: installs MkDocs and the Material theme into the runner.
  • Build site: runs mkdocs build --strict, which generates static HTML in ./site.

  • Configure Pages + Upload artifact: prepare and package the ./site directory so GitHub Pages can deploy it.

  • jobs > deploy:

  • Depends on the build job (needs: build).
  • Runs on Ubuntu as well.
  • Deploys the uploaded artifact to GitHub Pages using the official actions/deploy-pages action.
  • The environment block tracks deployment history in the repo’s Environments tab.

Key point: this workflow cleanly separates build (compile docs into site/) from deploy (publish to Pages). Using GitHub’s hosted Ubuntu runners means the process is reproducible and independent of my local Arch workstation.

Issues

  • Git push kept asking for a token.
    Even though I had SSH keys set up, the remote was still HTTPS. That made Git use the Git Credential Manager, which crashed with a SkiaSharp/Avalonia error. It fell back to username/password.

Fix: I need to switch the remote URL to SSH (git@github.com:...) so pushes bypass GCM entirely.

  • Pages initially only showed README.md.
    After renaming the repo to odonnellrory.github.io, GitHub Pages defaulted to serving the repo root. The docs folder wasn’t built at all.

Fix: I created a workflow under .github/workflows/gh-pages.yml that installs MkDocs, builds the site, and deploys the site/ folder via GitHub Actions. That was the missing link.

  • Local MkDocs install errors.
    Arch blocks pip install into system Python (PEP 668). The error suggested using pipx or a virtual environment.

Fix: I’ll either try sudo pacman -S mkdocs mkdocs-material or use pipx install mkdocs mkdocs-material to preview locally.

For now, I rely on the GitHub Action build and see my changes in post.

Improving mkdocs.yml

Currently my mcdoks.yml file is looking like this:

site_name: odonnellrory.github.io
repo_url: https://github.com/odonnellrory/odonnellrory.github.io
theme:
  name: material

Very basic.

Adding features like awesome-pages and git-revision-date-localized meant the build suddenly failed: MkDocs complained that the plugins weren’t installed.

What I Learned

  • MkDocs doesn’t auto-install plugins when you add them to mkdocs.yml.
  • The correct practice is to list them in a requirements.txt so both local environments and GitHub Actions know which Python packages to install.
  • GitHub Actions runs on its own Ubuntu runners, not my local Arch machine. This means every dependency has to be installed in the workflow, not assumed.

Issues Encountered

  1. Missing plugins: ERROR - Config value 'plugins': The "awesome-pages" plugin is not installed.
  2. Workflow duplication: At one point my workflow YAML had duplicate name, on, and permissions keys, which caused a fatal syntax error.
  3. Package installation: Initially my workflow only ran pip install mkdocs mkdocs-material. That wasn’t enough once I added plugins.

I Took

  • Created requirements.txt with:

mkdocs mkdocs-material mkdocs-awesome-pages-plugin mkdocs-minify-plugin mkdocs-git-revision-date-localized-plugin pymdown-extensions

  • Updated .github/workflows/gh-pages.yml so the build job runs:
- name: Install MkDocs + plugins
  run: pip install -r requirements.txt

Cleaned up the workflow file so there is only one set of top-level keys (name, on, permissions, etc.).

Verified the workflow sequence:

checkout > setup Python > install deps > mkdocs build --strict > upload artifact > deploy to Pages.

Confirmed that after fixing, the site built correctly with plugins enabled.

Screenshots, Live Preview, Table of Contents

Images and Screenshots

Image test

Workflow success ![Workflow success](./2025-08-25/workflow-success.png)

  • Set up an assets/ structure so screenshots can live alongside journal entries.
  • So now to add images, I create a folder for that days markdown file, and place the image file in there, like so:
.
├── 00-journal
│   ├── 2025-08-23.md
│   ├── 2025-08-24.md
│   ├── 2025-08-25
│   │   └── workflow-success.png
│   ├── 2025-08-25.md
│   └── .pages
└── index.md

This keeps it organised, rather than having one folder with every image in.

  • In Markdown, reference images with a relative path, like so: 

    ![Workflow success](./2025-08-25/workflow-success.png)

  • Enabled mkdocs-glightbox so clicking images opens them in a lightbox gallery.

  • Learned that images need to be stripped of metadata (to avoid leaking EXIF info) and compressed for speed.

Takeaway: screenshots make the journal feel real, but they need hygiene — redaction, compression, and a consistent folder structure.

Live Preview with mkdocs serve

  • Tried to use pipx for plugins, but MkDocs couldn’t see them. Learned that pipx is only for executables, not libraries.
  • The fix was to create a local Python virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
* Then run with python -m mkdocs serve (to guarantee it uses the venv version, not system MkDocs). * Site auto-reloads at http://127.0.0.1:8000 whenever I edit.

Takeaway: the venv keeps my local preview environment consistent with CI, and using python -m mkdocs avoids path confusion with Arch’s system packages.

Subcategories in the Table of Contents

  • Initially all my journal sub-headings showed up at the same level in the right-hand TOC.
  • Learned that MkDocs builds the TOC directly from Markdown heading levels (#, ##, ###, etc.).
  • Fixed by nesting headings properly:
## Problem
### Symptoms
### Root cause
mkdocs
  • Now my TOC shows a clear hierarchy.

Takeaway: Markdown heading structure isn’t just cosmetic — it directly controls navigation. Thinking in levels makes the site readable.

What I Learned

  • How to integrate images responsibly: folder structure, Markdown syntax, and lightbox galleries.
  • pipx wasn’t the right tool for MkDocs plugins, virtualenvs are the clean solution.

To Do:

  • Add captions under images for context.
  • Draft a standard .gitignore (ignore .venv/, site/, etc.).
  • Continue fleshing out sections for Hardware and Networking.

Sources

TO DO

  • Re-run the Actions job with the new permissions block and confirm the MkDocs site (with journal + hardware docs) actually renders.

  • If it still fails, capture the job logs to debug further.

  • Automate journal navigation updates (so I don’t have to hand-edit mkdocs.yml for each new entry).

  • Look into plugins like mkdocs-awesome-pages-plugin to auto-sort by filename/date.
  • Decide on journal entry format (timestamps vs. no timestamps).
  • Hardware list.
  • Add a To-Do list page for tracking new tasks.
  • Implement images.
  • Install NixOS on the laptop.
  • Update README.md.
  • Set up local preview (mkdocs serve) to test changes live before pushing to GitHub.
  • Explore adding mkdocs-minify-plugin and pymdown-extensions features.
  • Add a mkdocs.md page explaining the system for future readers (started today).
  • Test local preview (mkdocs serve) using pipx or pacman on Arch.
  • Add captions under images for context.
  • Draft a standard .gitignore (ignore .venv/, site/, etc.).
  • Continue fleshing out sections for Hardware and Networking.
  • Add actual documentation files as well, this isn't just a journal app! I can make a page for each thing that needs documentation. A page for my Arch machine, explaining it, a page for this mkdocs server and how to run it yourself.
  • If I set up a snipe IT inventory system, I could integrate it with my docs site. That would also be something to document.