27/08/25 - rewriting README¶

another day another dollar

opened laptop its my old ubuntu one i havent used in a long time.
which is good for this site because i can write how to set it up from fresh.

    git clone https://github.com/odonnellrory/odonnellrory.github.io.git
    cd odonnellrory.github.io

you'll need python, and if you're on a system with apt like Debian based systems this command should do it for you.

    sudo apt install python3 python3-venv python3-pip

oh ffs i haven't updated this thing in a year and a halfI guess that's a bonus to this docs project, because I'll have this problem again in a year and a half.

    sudo apt get update

so for the README

    git clone https://github.com/odonnellrory/odonnellrory.github.io.git
    cd odonnellrory.github.io

you'll need python, and if you're on a system with apt like Debian based systems this command should do it for you.

    sudo apt get update
    sudo apt install python3 python3-venv python3-pip

btw ctrl+a then ctrl+k deletes everything in the command line (yes that is the right term, it deletes everything on that line, the line you write the commands, the COMMAND + LINE)

Troubleshooting

“The 'awesome-pages' plugin is not installed”
Activate the venv and reinstall deps:

source .venv/bin/activate
pip install -r requirements.txt

You can edit the names of the files with the #title on line one.

new README¶

Introduction¶

This site uses MkDocs + GitHub Pages.

Once this is set up, I edit the website by simply writing to a markdown file on my machine.

The files are saved locally, push them to GitHub, GitHub Actions will host the repo as a website. MkDocs will organise the Markdown files automatically into navigatable HTML.

I plan to use this to document a lot of the projects that I have made over the last year, and any projects that I work on in the future.

Notes are in /docs/00-journal/.

Installation¶

    git clone https://github.com/odonnellrory/odonnellrory.github.io.git
    cd odonnellrory.github.io

Host locally¶

Debian (Ubuntu, Mint, etc)¶

You'll need python to run it locally.

    sudo apt update
    sudo apt install python3 python3-venv python3-pip

Instructions¶

You are going to make a virtual environment using python, that's what python3-venv is for.

Inside this virtual environment, you will install the dependencies.

The dependencies are listed in a text file in the repo's root directory. requirements.txt

Python will install what is listed there using pip. That's what python3-pip is for.

    python3 -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt

Run Locally¶

Now to run the website locally on your machine, run:

    python -m mkdocs serve

Now go to http://127.0.0.1:8000 and there's your website.
Here you can preview changes live.

Sources¶

GitHub Pages MkDocs MkDocs How to Deploy MkDocs Material

Interesting I had to delete the tic tac toe's README.md file. I guess MkDocs cares about my repo's README.