1. Principles and practices & Project management¶

This week I set up the Windows Subsystem for Linux, got started with Git as well as MkDocs and came up with a rough sketch of what i want my final project to be.

Tools¶

As I have heard the documentation process takes up most of your time during FabAcademy. So far the following software tools have served me really well.

Notepad++ is a simple but powerful text editor and Notepad replacement that supports several common programming languages.

Microsoft PowerToys is a set of useful tools including image resizer, advanced paste, PowerRename and mouse without borders. That last one comes in especially handy if you are working on multiple computers at once.

Greenshot saves a lot of time with its ability to set up a custom storage location and automatically open a new screenshot in MS Paint or a different program of your choosing.

I’m sure this list will keep on growing as i work on more assignments.

Setting up WSL¶

The first step in the process of getting your website up and running is setting up WSL or Windows Subsystem for Linux. It could be because english is not my first language but i feel like that name should be the other way around. Just to be clear with WSL you are installing a Linux environment inside of your current Windows operating system. Anyways, let’s get started!

Open PowerShell or Command Prompt as an administrator and enter wsl --install to install an Ubuntu environment
- by adding -d <DistroName> you can choose a different Linux distribution
 - wsl --list --online will show you a list of all available distributions
when the installation is done you are going to need to restart your computer
Ubuntu should now be an app that opens a terminal
on first start it will ask you to setup a new user that will be considered an administrator
from this point onward it is recommended to regularly update and upgrade your packages by entering
sudo apt update && sudo apt upgrade

Getting started with Git¶

Since the website’s repository will be hosted on GitLab you will need to install Git and pair your computer with your GitLab repository via SSH

in your WSL terminal enter sudo apt-get install git followed by entering git init

next you will need to set up your Git config file by entering the following commands

git config user.name "<Your Name>"
git config user.email "<you@example.org>"
git config --global user.name "<Your Name>"
git config --global user.email "<you@example.org>"

don’t just copy and paste it, remember to actually type in your name and e-mail
enter ssh-keygen -t ed25519 -C "Comment" to generate an SSH key pair
the -C "Comment" part’s purpose is to let you keep track of what this key pair is used for
I for instance wrote -C "Home Workstation so GitLab will automatically label this key accordingly when we add it in the next step
you can specify a name and password for your key file but i just went with the default name and no password by simply hitting enter when asked
the gibberish you now see in your terminal is the new key’s fingerprint, keep it secret, keep it safe!

to add the key to your GitLab account click on your avatar in the top left corner and go to edit profile

click on the SSH Keys menu and add a new key

open your newly generated “id_ed25519.pub” file with an editor (such as Notepad++) and copy all of it’s content

paste it into the box labeled “Key” in GitLab and click on “Add key”

after a few seconds you should receive an e-mail letting you know that a new SSH key has been added to your GitLab account
- while we’re still in here let’s enable dark mode, a little bit below the “SSH Keys” menu you will find “Preferences”
- I’m a dark appearance, blue theme, monokai syntax kind of guy, what about you?
add a new folder in your WSL environment by entering mkdir <foldername> in the terminal
navigate into that new folder by typing cd <foldername>
here i added another subfolder but you don’t have to
this is where all of the files you need for your website will be living
in your GitLab repo, click on the blue button labeled “Code” and copy the URL listed under “Clone with SSH”

enter git clone <link to your repo> in the terminal to basically download your repository
since this is the first time using the new SSH key for anything it will ask you to confirm the connection by typing yes

these files are kind of unnecessary but a good test to see if everything works so far
since i am going to use MkDocs i deleted all of the previously downloaded files and replaced them with the files found in the Student template MkDocs repository

navigate to the directory where your repo files are via the terminal and enter git add . to stage all changes (added, deleted or changed files)
confirm that all files and changes have been successfully staged with git status
commit the staged files with git commit -a -m "comment"
- don’t forget to include an annotation so you can keep track of what you changed at a later date
all there is left to do is push all local changes to your GitLab repository by entering
git push origin main

GitLab will take a little while to deploy the changes to your website, you can keep track of the status by clicking here

when deployment has been successful you can open up your website and bask in the glory of… the template you are about to change…
before you can customize the site though: more setup 👇

Installing MkDocs¶

to use MkDocs and see the changes our site locally we’re going to need Python
by now there should be a whole lot of text in your WSL terminal, if you are like me and find it distracting to look at a wall of gibberish hit CTRL + L to clear the console
to install Python enter sudo apt-get install python3 followed by sudo apt install python3-pip and sudo apt-get update
next we can install MkDocs by typing sudo apt install mkdocs
with mkdocs serve we should now be able to start our locally hosted website so we can edit and see the changes without having to push to GitLab every time

looks like we’re missing something essential, good thing the template came with a requirements.txt file
by entering pip install -r requirements.txt everything we were missing should be added

uhhh… or not…
fortunately we only need to install and enter a virtual environment to be able to use pip, otherwise it would conflict with other package managers
enter sudo apt install python3.12-venv and confirm the installation
now we can create a virtual environment by first navigating to the base directory with cd (if you aren’t there already) followed by typing python3 -m venv .venv
you can enter it with source .venv/bin/activate and leave it with deactivate

for now we will stay in the virtual environment and install the missing components
navigate to your repository directory and enter pip install -r requirements.txt

this should have taken care of the last necessary bits so let’s try mkdocs serve again

and there it is folks! open up your favorite browser and enter localhost:8000 to see your creation
if you want to stop the server hit CTRL + C
- you don’t need to stop the server to change any files, every time you save your changes or add anything it recompiles automatically

Customization¶

To start off let’s talk about some basics

the general folder structure of a markdown based website looks something like this

.
└── root
    ├── mkdocs.yml
    ├── requirements.txt
    └── docs
        ├── index.md
        ├── about
        │   └── index.md
        ├── assignments
        │   ├── week01.md
        │   ├── week02.md
        │   └── ...
        └── projects
            ├── final-project.md
            └── sample-project.md

starting in the root directory we find an mkdocs.yml file, this is where you define your basic site info, link to extensions and plugins and adjust the global style
as we have talked about above, the requirements.txt is used to install said plugins
next up is the docs folder with its own index.md file
every folder and subfolder with a .md file generates a page on your website

Here is a little example of the index.md file found in the docs folder which builds my Home page

# Home

__Hi there and welcome to my FabAcademy 2025 page__

This is where all of my **[assignments](./assignments/week01.md)** and **[projects](./projects/final-project.md)** will be documented

resulting in:

You might have already seen my About page

which is built with this (slightly abridged) code:

# About me

![](../images/profilbild.png)

Hi! My name is Julian Baßler. And so on and so forth...

## My background

As i have always been interested in computers and technology...

Something about parameters, link benchy... **[3Dbenchy](https://www.thingiverse.com/thing:763622)** 

Pandemic, motivation, sad face emoji...
E-mail notification, happy face emoji...

Link to HRW FabLab... **[HRW FabLab](https://hrw-fablab.de)** 

10 minutes and all that...

Maintain, upgrade, learn :)

Now that i have shown you some examples we can focus on the fun part (depending on who you ask)

head into the root directory and open mkdocs.yml with your favorite text editor
for the most part the comments in this file are pretty self explainatory but if you want to dive deeper into it than my personal customizations feel free to check out MkDocs for more detailed guides
the first thing of course is to change the site_name, site_description, site_author, site_url and copyright parameters
next i opted to remove the whole social media section, since the only platform i am really active on is YouTube and my channel only has Destiny 2 related content, so this didn’t feel like the right place to plug that
_{^{_{^{i still need those red boarders from Garden of Salvation though, so if you want to farm some runs let me know!}}}}
by the way that small text was achieved by writing
 small text 
- you can further decrease the size of the text by wrapping it in more
  
after that i changed up the theme settings a little, here is what i went with:

theme:
  name: material
  palette:
    scheme: slate
    primary: custom
    accent: custom
  font:
    text: Ubuntu
    code: Ubuntu Mono
  icon:
    logo: fontawesome/solid/globe
  favicon: images/globe.svg
  features:
    - navigation.tabs
    - navigation.instant

a part of me wanted to set the font to Comic Sans but i decided against it because this right here is very serious business
anyways let me explain some of the things i just changed
- scheme: slate basically puts the whole site in dark mode, which as you might have guessed i am quite a big fan of
- next i added custom primary and accent colors by creating a stylesheets folder in the docs directory in which i placed an extra.css file and wrote

:root {
  --md-primary-fg-color:        #314d6e;
  --md-primary-fg-color--light: #6a7f98;
  --md-primary-fg-color--dark:  #1a2c41;
}
:root {
  --md-accent-fg-color:        #576e8a;
  --md-accent-fg-color--light: #7689a1;
  --md-accent-fg-color--dark:  #3e5065;
}

to find the right colors i used the ColorKit Color Picker
if you want to learn more about changing colors in Material for MkDocs take a look at these guides for the built in color palette and custom colors
the last things i changed were the logo and favicon which are somewhat hidden, you can find them at the end of this rabbit hole 👇

once i picked out the one i wanted, i copied it and pasted it into the images folder found in the docs directory

that’s about it for now, go ahead and try it for yourself but maybe open a window first and remember to stay hydrated!