1. Principles and practices
For me the goal of this week is getting into the habbit of documenting my process and learning the basics of web development.
Goals
- [x] Read, sign the student/instructor/lab agreements, and commit to your repos
- [x] Work through a git tutorial
- [x] Build a personal site in the class archive describing you and your final project
Research
I had some basic we development experience from an internship, but as its had been over 10 years I wanted to play around with the tools before jumping into a tutorial. The first steps were getting some software installed and getting the files from the FabCloud synced down to my laptop
Software installed to achieve goals
1. Read and Sign the agreements.
1.0:
Before I could sign the agreements I needed to clone my fablab repo onto my machine so I could then make edits and push changes.
I downloaded Homebrew following the instructions on the website. An after some things not working I noticed that there are follow up instructions on in the terminal. Under “Next Steps” there are some lines you must copy into the terminal in order to add homebrew to your path, this is important as it means otherwise you cant use the brew commands
After this I used:
git clone https://gitlab.fabcloud.org/academany/fabacademy/2025/labs/creativespark/students/carl-mcateer.git
I then had a bit of trouble with my username and password, but after some resetting I was able to clone my repo.
After this I had to navigate to my repo in the terminal. The two basic commands I used were ls and cd
ls
cd
LS lists the all the files and folders in a directory (see below)
Note: I used the native file converter on my mac to change the screenshots from png to jpg
1.1 - Agreements:
Went to this link and copied the text of the student agreement. I then made a new file using
touch agreement.html Open this file and copy in the continence of another page on the site and add replace the continence of the main div with a paragraph tags that contain the signed agreement.
We also need a way to navigate to this file so I have added the following to the navigation bar at the top of each file
1.2 - Pushing:
After these were added the following git commands sent the updates to the repo.
First use ls and cd to navigate to the main directory.
git add .
git commit -m "My Agreement Page"
git push
1.3 - Hit refresh on your site 10000 times:
After that push my files have been launched from my little laptop onto the world wide web. To cap things off and see the fruits of my labor I go to my live page and git the refresh button until I can see my agreement in all its glory.
End (Or is it?)
Addendum
The keen eye might notice that I have updated my website since I wrote this page. After seeing Mkdocs in action on the Monday recitation I just felt that the ease of writing directly in the document rather than having a separate word doc that I would translate into HTML was worth committing to early on.
So to that end see my step by step for installing Mkdocs with the Simple-blog theme below
New tools
In the spirit of using more open source tools I have switched my text editor to Zed. This has the advantage of an integrated terminal so I don’t need to to split screens with the Mac terminal Also its very fast and has very nice tools that all run out of a unified command pallet.
SSH Keys
When I first used git for this project I was able to clone and the repo and sign in with my credentials in the terminal.
Having seen the recitation it was made clear that SSH keys are an easier and more secure way of authenticating
Using the notes from Julian Gallimore’s recitation on I set up the following keys.
ssh-keygen -t ed25519 -C "ssh-for-gitlab-fabcloud"
I then added the public key to gitlab via the setting menu.
I then confirmed my credentials using
git config user.name "My Name"
git config user.email "My@email.com"
And confirmed everything was working using git status
Setting up a virtual environment
An early mistake I made was not using a virtual environment. This caused lots of issues when using tools installed through PIP and Homebrew. The solution to this is to create a environment on your machine that is separated from the rest of your programs.
This allows you to install programs here and not have to worry about how they affect other things on the system.
2.1
use cd to navigate to your root folder and run the following command
python3 -m venv my_env
You can now enter your environment with
source my_env/bin/activate
If at any stage you need to get out of ‘my_env’ just type deactivate into the terminal.
2.2
Now that you are sequestered into you nice new environment you can install all the tools you will need. Make sure you are in your environment before you do the following steps, your terminal prompt should look something like this with your environment in the brackets at the start of the prompt.
(my_env) carlmcateer@Carls-Laptop carl-mcateer %
First of is installing homebew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Then install the following tools
brew install python3
pip3 install --upgrade pip
pip3 install mkdocs
pip3 install mkdocs-material
pip3 install mkdocs-material-extensions
pip3 install mkdocs-simple-blog
pip3 install mkdocs-video
Starting with Student template.
In the recitation for week 1 Julian shared a template for student documentation.
After making a backup of my old site in Finder pasted in the student template from the above link.
2.3
Now to customise the template. Fist step was to copy and paste the content of all the pages into there new corresponding markdown pages.
The default theme in Mkdocs is Material but I wanted to use something a bit cleaner and simpler. My preference was simple-blog by Fernando Celmer.
First step is editing the mkdocs.yml
The theme can be set as below
theme:
name: simple-blog
sidebar: true
navigation_depth: 3
highlightjs: true
- yaml
- python
- zsh
components:
site_name: true
title: false
We also need a way to embed video on the site so the following plugin is added to mkdocs.yml as well
plugins:
- search
- mkdocs-video:
is_video: True
video_autoplay: True
video_muted: True
video_loop: True
The personal information can also be added at this stage, mine looks something like this.
site_name: Carl McAteer - Fab Academy
site_description: Fab Academy documentation site for Carl McAteer
site_author: Carl McAteer
copyright: Copyright 2023 Carl McAteer - Creative Commons Attribution Non Commercial
site_url: https://fabacademy.org/2025/labs/creativespark/students/carl-mcateer/
2.4
This is a good time to see how our site is looking on our local server, so run the following command (making sure you are in your directory)
python3 -m mkdocs serve
This will output something like this (its normal don’t panic 🫨)
INFO - Building documentation...
INFO - Cleaning site directory
WARNING - Doc file 'assignments/week05.md' contains a link '../images/w5/w5-sc2-1.jpeg', but the target
'images/w5/w5-sc2-1.jpeg' is not found among documentation files.
INFO - Doc file 'assignments/week06.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week07.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week08.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week09.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week10.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week11.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week12.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week13.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week14.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week15.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week16.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week17.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Doc file 'assignments/week18.md' contains an unrecognized relative link 'TODO', it was left as is.
INFO - Documentation built in 0.32 seconds
INFO - [11:47:49] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [11:47:49] Serving on http://127.0.0.1:8000/2025/labs/creativespark/students/carl-mcateer/
The most important section is the url on the last line.
http://127.0.0.1:8000/2025/labs/creativespark/students/carl-mcateer/
Copy and paste that into a browser on your machine and you should see your site.
This is a fantastic way to preview your site before you push to gitlab.
Push it
Once you are happy with your local view of your site you can push it to git lab.
2.5
To do this we are using the holy trifecta of commands that will be burned into your brain over the course of this diploma.
git add .
git commit -m "Some comment"
git push