2. Project management + Git

Linking your repository and Gitlab

Terminal commands

Your first move is to create the directory you'd like to work in. I set up a dev folder, because that's what Henk has, and he's my code-idol.

Use the cd command to navigate to the home directory and jump around from using the various cd commands:

cd folder-name
cd ..
cd ../..
cd previous-folder-name (to go back)

To make a directory from Terminal, use the following command:

mkdir the-folder-name

If you'd like to create the folder AND a file nested in it, use this sequence:

mkdir the-folder-name touch thefilename.txt

One of the best parts about this week has been learning how to execute commands from Terminal. It's super useful and makes you feel like a hacker.

SSH keygen

In terminal run the command: ssh keygen

You are asked where you'd like to save the SSH key — I set used: /Users/dylanheneck/.ssh/id_ed25519

To check that everything was created properly, run ls -altr in Terminal (the -altr flag shows hidden folders, as opposed to just running ls)

Alternatively, ~/.ssh also checks that it exists

If you're going to look for the folder from GUI, then make sure to hit shift+cmd+. to show hidden folders (folders with periods in front of them are hidden)

Now, run cd .ssh in Terminal to return to the .ssh directory

While here, run cat id_ed25519.pub to show the contents of the id_ed25519.pub file

The output will be the SSH key

Copy that and paste it in the Gitlab SSH Keys tab

In your .ssh folder, create a file called config

Add the following text:

config file

Run in Terminal: ssh git@gitlab.fabcloud.org

Connection will open, but closes automatically “Connection to gitlab.fabcloud.org closed.”

Next, go to the gitlab.fabcloud.org repository > copy Clone with SSH

ssh copy

In Terminal, navigate to the dev folder and, you can either follow the next steps in here, or create a new directory within dev

Once you're in the right directory, run:

git clone git@gitlab.fabcloud.org:academany/fabacademy/2025/labs/waag/students/dylan-heneck.git

When I was testing if this worked, there was an error!

The error was regarding: user.name and user.email

Solution: Run the git.config commands seen below:

git setup test error

List of resources:

Creating our documentation website

CI/CD, SSGs, Mkdocs

CI/CD (Continuous Integration and Continuous Delivery/Deployment) automates testing, building, and deploying your project whenever you make changes Static Site Generators, like MkDocs, convert Markdown files into static HTML pages MkDocs is a Python-based SSG designed specifically for creating project documentation

Setting up Mkdocs

Everything I've written below is beautifully summarized, in much more concise fashion here: Fablab Mkdocs tutorial.

We begun by installing a few extensions for VSC:

markdownlint
gitlens
markdown preview enhanced
markdown all in one

Then we downloaded Python and Pip. Many modern systems use python3 for Python 3.x and reserve python for legacy Python 2.x. Running the command python —version didn’t work, so I checked my AI answer engine as to why terminal was returning “python --version (command not found)“ and it suggested trying python3 —version, due to alternate naming conventions.

Next up, mkdocs. MkDocs can be integrated into CI/CD pipelines to automate the building and deployment of documentation. Without mkdocs we’d be knee deep in html! In terminal we ran a command to download mkdocs and to update it to the latest version:

pip3 install mkdocs && mkdocs —version

From this point on I made a lot of mistakes. The first one being that I tried to rush ahead while Henk was presenting how he was setting up the Waag 2025 site. I missed out on reviewing the sequence of how he put things are together. Then, over the course of the rest of the afternoon, evening, and following afternoon, I briefly managed to fix the issues, I thought, but actually got lost somewhere between the server and my computer, which Neil later described as a 'confused zone'. I got into a bit of a spiral of removing repositories, starting again, and things not working. Eventually, I reached out for help. I will post a screenshot of my conversation with Henk below.

Henk figured out that I’ve deleted the repo on my laptop (ie. getting lost between my computer and the server) and he gives me the terminal commands to set everything back up. I was struggling to fix this problem from VSC.

Henk to the rescue

So, I deleted everything and started again, I set up the Gitlab clone again and ran mkdocs new dylan-heneck

This created the following: - A project directory: /dylan-heneck - A config file: mkdocs.yml - A folder and a file: /docs/index.md

The next step is to create a file from the Gitlab repository. Call it .gitlab.ci.yml and when it gives you an option to 'Apply a template' choose HTML.

However the work wasn’t done, there was still an error in the pipeline.

Pipeline error

To fix this I had to copy the yml files Henk had used when setting up the repository for the Waag-2025 site. I found those here I updated the .gitlab-ci.yml file with the contents from Henk’s yml file and voila! It worked! I remembered from class that this new .gitlab-ci.yml file wasn’t working until Henk copied across another file called requirements.txt because there were errors when that wasn’t in the repository as the yml file called on it. This txt file makes an appearance again when I choose a new Mkdocs theme.

At this stage, we should have a bare minimum working Mkdocs website.

Some notes

At home I did a bunch of research on terminal, markdown, and repository management. Considering my previous failures, I wasn’t feeling so confident, so I watched a YouTube video on how to set up the Mkdocs Material theme. It was good to see someone else assemble all the relevant parts. He did it in a slightly differently way, but ultimately, it was the same. It gave me a better understanding of what is going on. Notably, the YouTuber explains a bit more about what is going on in the the ci.yml file, and what the /.github folder does. Later on, Julian's Version control & Gitlab recitation does this very well!

Both Henk and the YouTube video I watched helped teach me how to commit files to the main repository, and understand a bit more about what’s happening there. I feel like I’ve learned a lot already! And, yet, it’s also just the tip of the iceberg, a steep learning curve, if you will. Here are those commands:

Stage Changes: git add . prepares all changes for committing.
Commit Changes: git commit -m 'message' creates a snapshot of those changes.
Push Changes: git push uploads those snapshots to the remote repository.

Feeling confident, I decided to start a new blog for my Nederlandse tal studies. I was able to successfully create a repository on my desktop and connect it to my personal GitHub. The two major differences were that 1. Because I had to make a separate SSH key, it meant that I had to update the /.ssh config file, which now read like:

$ cat config
Host gitlab.fabcloud.org
 User git  
 IdentityFile ~/.ssh/id_ed25519
 IdentitiesOnly yes

Host github.com
 User bootsandcats
 IdentityFile ~/.ssh/dutch_spullen
 IdentitiesOnly yes

The second major difference is that in order to view the new blog, because I don't have a website, I can only view it locally. In order to find out how to view it locally, I had to navigate to the correct directory and run the command mkdocs serve, it outputted this: http://127.0.0.1:8000/ — so, put that in my browser and BAM! I only later learned the importance of using cmd+c while in Terminal to stop the development server. This was originally quite confusing as it seemed that Terminal kept getting stuck in a state of being broken.

One additional note, having AI has been quite helpful throughout the process of setting up the new blog as it helps me to answer questions like:

How can I have an ssh for more than one site — which is how I learned about editing the /.ssh config file
What does IdentitiesOnly do? — to better understand my environment
And mostly that it helped me understand errors I was getting in VSC and terminal

The best part about AI is that even if I’m not exactly sure how to ask the question, I can keep asking in a direction, and it’s very good and helping me get towards where I’m hoping to go.

List of resources:

The top Mkdocs themes
Use the Google search bar on the course directory page
A previous student's Mkdocs process

Customizing Mkdocs

When setting up Mkdocs, it comes ready to go with a few preset themes. Material seems to be the most popular of them. However, I was looking for something a bit different, so I checked out Mkdoc's Github. On it was a ranked list of 30 open-source theme projects. My hope was to find a clean + simple theme, and I was in luck!

This is what Material looks like (a bit lame if you ask me):

Material theme

Setting up a theme

Instead of Material, I decided that the theme Terminal would suit my documentation site. I had originally dabbled with Lantana, but ultimately, Terminal won. Funnily enough, Henk, my coding idol, happened to be using the same theme. This was a sign that I was on the right path!

In order to activate the Terminal theme, I had to run the prompt in my computer's Terminal:

pip install mkdocs-terminal

I also had to update my mkdocs.yml file, replacing theme: material with theme: terminal.

Now that I had my theme, it was time to start customizing. This was a bit of a struggle at first. I couldn't figure out how to update the colors from the mkdocs.yml file, even though I was using the markdown code that I had seen others use to customize their sites.

So, I dug around a bit and eventually navigated to the GitHub repository for the Terminal theme. There was a page on the developers documentation site about color palettes. I chose the palette: gruvbox_dark option, but something wasn’t working.

After I a bit of nitpicking I realized that there was a spacing error in my markdown code:

theme: 
  name: terminal
    palette: gruvbox_dark

The line for palette was tabbed too far to the right, apparently. Here's the pipeline error I was getting that showed me what was wrong (mind you I needed Samuel's help to figure this out).

Markdown spacing error

Now, with that taken care of, there was a new error. My requirements.txt file needed updating. I was still pointing to mkdocs-material ~=9.0 in that file.

requirements.txt update

I edited the requirements.txt file to include mkdocs-terminal ~= 1.6.1 -- Upon Samuel's recommendation, I searched for a version number for Terminal. I believed it might be 1.6.1 after searching for mkdocs-terminal pip. But it seems that 1.6.1 wasn’t a version I could use:

Terminal version error

So, I updated the requirements.txt file to mkdocs-terminal ~= 4.7.0 and it worked!

CSS

In order to customize the Terminal theme even further, I had to create a css directory in the projects /docs folder (NB. it must be in docs - I had an issue where it wasn’t and the css didn’t work). Below is how I used my computer's Terminal to do that (make new directory + make new file):

mkdir stylesheets touch extra.css

For extra.css to become functional, I had to update the mkdocs.yml file in VSC:

extra_css:
  - stylesheets/extra.css

Now, that the css file is set up, I have to start identifying the elements that I'd like to adjust. From the Chrome browser, press option + command + i to open the developer tool. In the top left corner of the developer tool is a button that looks like this hover tool and by selecting that mode you can then hover over elements on the webpage and inspect the html. This is useful for finding the names of different elements on the page and to see how they're styled. Head back to the extra.css file and input code to change elements like h1, body, a, and so on…

By using that feature, I was able to identify what to override in the extra.css file. For instance, I chose to change the spacing of the site.

.container {
  max-width: 90%;
}

For some of the stylistic changes I wanted to make, specifically with getting rid of a certain table of contents element, the theme's documentation had special instructions on how to get rid of it. Basically, add a line to features in your yml file:

theme:
  name: terminal
  features:
    - navigation.side.toc.hide

TOC Terminal

The documentation site for the Terminal theme was extremely useful for helping me understand how to customize my site.

To figure out to figure out what color I was going to use for the website, I found a pallet generator called Coolors that was recommended on a Reddit thread. For a long time now I've used Google's search engine powers to help me find content on Reddit, which I consider a more honest answer to a lot of questions I've had over the years, to do that, search site:reddit.com whatever you're looking for. On Coolors I uploaded a photo that I liked the vibe of, it then took a bunch of the colors from that photo to generate a palette. This was mine.

Palette origin pic

My first palette

You're probably wondering about how I've been managing my beautiful screenshots? Well, I found an image compressor called ImageOptim. I happened to find it while perusing the blog of a former Fablab participant. Here's a quick tutorial on how to use it.

The markdown code to add images to your file is ![Subdirectory Image](folder/image.png).

I was finding it particularly annoying to have to click through many file directories in order to drag my ImageOptim'd photos into the right place. I asked AI how to use the Terminal on my computer to move files and it gave me these options:

mv example.txt ~/Documents
mv file1.txt file2.txt ~/Documents
sudo mv example.txt /restricted_folder/
mv example.txt ~/Documents/new_example.txt (this is how you change the file's name in addition to moving it)

The only issue I encountered while trying to do this was in regards to permission limitations on my laptop. AI also helped me answer this:

File moving error

File permission settings

NB. For creating my site structure, I downloaded the Student templace Mkdocs /docs folder and put that into my project.

Over time I made more CSS updates.

Notably, I had some help figuring out how to make just the first item from a list on a second nav element dissapear:

nav ul li:first-of-type {
  display: none;
}
nav:first-of-type ul li:first-of-type {
  display: initial;
}

It makes the first item in all nav list elements dissappear and then the second bit instructs to undo that for the first nav list only.

Creating the Index page tiles

The last major CSS hurdle that I had to face was setting up tiles. I was struggling to understand how link relatively. In mkdocs there’s a nav element that needs to be added to the mkdocs.yml file and then the site should be indexed within that. I hadn’t done that because the site already looks fine; all of the pages were indexed correctly based on how the .md files were arranged in the directory’s folders. That just meant that when it came time to setting up tiles that linked to pages, I had a major headache on my hands.

Below is the code that the theme’s developers gave for how tiles were coded. From there, I made many iterations to try and figure out how to get the link_href function to link to another page, but nothing was working. Eventually I got it to work.

---
tiles:
  - caption: 'Tile 1 Caption'
    img_src: https://example.com/image1.jpg
    alt_text: 'Description of Image 1'
    link_href: https://example.com/page1
  - caption: 'Tile 2 Caption'
    img_src: https://example.com/image2.jpg
    alt_text: 'Description of Image 2'
    link_href: https://example.com/page2
---

# Page title

To begin, add navigation to the mkdocs.yml file.

nav:
  - Home: index.md
  - Folder 1: 
        - File name: ./folder-1/file-name

I had done exactly this, but the example code from both AI and the theme developers had left the .md on the end of the file-name item: - File name: ./folder-1/file-name.md. Don’t add .md to the end of file-name. lol. And also, only use ./ to start the file path.

With both of those speed bumps behind me, the rest was a breeze. Here’s how to configure the tile links properly:

---
tiles:
  - caption: 'Go to Home Page'
    img_src: ./images/icon-tiles/home_icon.png
    alt_text: 'Home Page Icon'
    link_href: ./index.md
---

Extra resources:

Markdown cheatsheet