2. Project management

This week I got started setting up the website and finding a workflow for documentation. I have some prior experience with using GIT for version control but that was several years ago. I decided on using Markdown for the site and VSCode for IDE.

Setting up GIT and MKDocs

I had to do this twice as I am working on two machines. One being my beloved triple-monitor setup at home and the other my laptop at work. As I’m documenting as I go, I use a workflow I’m comfortable with which is having a .txt file with my notes in Notepad++. It’s especially strange since most of the work I’m doing is in VScode anyway but it’s something I’ve gotten used to doing both in school and when I’m working on other projects so I’ll stick to that for the time being. This means I use a lot of indentations in my notes and they’re all ordered sequentially in the order I did them. The full notes are available in the dropdown menus below but there’s also a condensed summary for each.

Notes from January 24th 2025.

Summary:

Setting up GIT and MKDocs on both machines. Had some issues with the SSH key on the laptop but that was resolved by restarting. Also set up MKDocs and started using the VSCODE for markdown.

Useful Commands:

"winget install Git.Git"
    Installs Git using Windows' built in command-prompt package manager

"winget install python.python"
    Installs Python, You can choose specific versions by appending the version number. 
        For example:
            "winget install python.python.3.13"

"pip install mkdocs"
    Fairly self explanatory. Installs mkdocs. 

"mkdocs serve"
    Runs a live preview of the site at localhost:8000.
    Refreshes automatically whenever it detects changes in files.
show / hide full notes 
    Started by setting up Git on my machines. I have a Desktop at home and a Laptop for working at the Lab. 
    I use Microsoft OneDrive to mirror the two machines' user folders. (Desktop, Documents etc.)
    I used "winget", Microsoft's Command-Prompt package manager:

        "winget install Git.Git" 

    While installing Git I also decided to reinstall Python to get a clean slate. "winget install python.python.3.13"
    Once Git was installed I opened up Git Bash and started off by going through the configuration steps:


        "cd ~" This moves me to the "Home" Directory, In this case being /c/Users/maggi
            Had trouble finding "~" on my Icelandic keyboard. After some mild button mashing I figured out it's CTRL+ALT+' 
            (The key two to the right of P)

        git config --global user.name "Magnús Pétursson"
            Sets global user name to "Magnús Pétursson" 
        git config --global user.email "magnus@magnusp.is"
            Sets global user email to "magnus@magnusp.is"
        I use --global since this is the only repository I'll be using on these systems for now.

        git config --global --list
            This is just to sanity check that the info is correct.

        ssh-keygen -t ed25519 -C "<your email here>"
            This generates the SSH key for the git instance. "ed25519" is the type of SSH key, (https://gitlab.fabcloud.org/help/user/ssh.md#add-an-ssh-key-to-your-gitlab-account)

        cd .ssh/
            Navigates to the SSH directory in /c/Users/maggi
        cat id_ed25519.pub
            cat checks the contents of files. In this case I'm running it just to make sure they key generated properly and in the right place. 

    I log into gitlab and go into my preferences and "SSH Keys" on the left sidebar. Since I have two machines I use two separate keys for each machine. 
        I use "cat ~/.ssh/id_ed25519.pub | clip" to copy the contents of "id_ed25519.pub" (The Public Key) into my clipboard
        Pasted the SSH key into the field and set a machine title . I unchecked the expiration date but this may not be strictly best practise
        Having some strange issue where the "Add Key" Button is greyed out when setting this up on my Laptop,
        It may be that I'm forgetting a step since I did the desktop. Documenting as I go on the second run-through.
        Unsure what the issue was but restarting the laptop solved it instantly. 

    After setting up the SSH key for the laptop I go to check if everything works on the laptop.
        "cd ~/OneDrive/desktop/FabAcademy/git/magnus-petursson"
            Navigate to the folder where I have the local instance of my repository
        "git pull"
            Run to make sure OneDrive isn't messing with anything. It returned "Already up to date" So I'm good. Always pull before doing any work.

    I cloned the MKDocs Student Template into my repo by going to "git@gitlab.fabcloud.org:academany/fabacademy/templates/student-template-mkdocs.git" and using the "Code" Dropdown to copy "Clone with SSH"
        "git clone git@gitlab.fabcloud.org:academany/fabacademy/templates/student-template-mkdocs.git"
    Used the dropdown menu to get my REPO into VSCODE, Making sure the directory matched as VSCODE automatically clones it when opened. 
    Inside VSCODE I signed the student agreement. 
    Using VSCODE's Repository UI is very convenient. I'll probably not rely on it completely when I'm adding images etc. But it's convenient when working on the site.

Notes from January 28th 2025.

Summary:

Set up MKdocs on the laptop. “pip install mkdocs” Ran into trouble doing “mkdocs serve” due to missing dependencies in the themes. Needed to run “pip install -r requirements.txt” which I found after looking in .gitlab-ci.yml. Also got VScode set up on the laptop and installed a markdown preview extension in VSCode. This extension gives a live preview inside VScode as you make changes. It’s a bit faster than “mkdocs serve” but doesn’t display the site theme, header or footer. Mostly useful for making sure formatting is correct.

I had an hilarious interaction with OneDrive where I placed the local instance of the repository on my desktop and cloned the repo into itself by accident. This seemingly caused OneDrive to start downloading the repo into itself recursively like a nesting doll. Moving the repo to a non-Onedrive handled folder solved the issue. I suggest putting it somewhere like C:/FabAcademy.

Show / hide full notes 
    Starting on mkdocs. Working on the laptop.

    Trying to run mkdocs serve to preview my work threw an error:

        ERROR   -  Config value 'theme': Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs

        Aborted with a configuration error!
    I was missing the "materials" theme. 

        I ran python -m pip install mkdocs-material

    Running mkdocs serve now gave me a different error:

        ERROR   -  Config value 'plugins': The "git-revision-date-localized" plugin is not installed

        Aborted with a configuration error!

    Realized these dependencies should be somwehere in the student template and definitely in the config for Gitlab CI. Checked in ".gitlab-ci.yml" and sure enough there it was:

        "before_script:
          # install Git for the mkdocs revision plugin
          - time apt update && apt-get install -y git
          # Install mkdocs and theme
          - time pip install -r requirements.txt"

        This refers to requirements.txt which is right there in the folder.

        so I just ran "pip install -r requirements.txt" on my machine and it installed "mkdocs-git-revision-plugin" and the materials(Although I already had those from "python -m pip install mkdocs-material"). 

    Running mkdocs serve again:

        It ran, Time to check it out:
            In browser I go to localhost:8000

        Everything looks correct. Time to start playing around with it.

        First order of business is editing mkdocs.yml in vscode
            I find and replace "your name" with my name.

            I  delete the "Socials" segment 

            Do a commit and push to have this ready before I start messing with the aesthetics.

        Doing the commit I forgot to add mkdocs.yml so "git add mkdocs.yml"
        after pushing I noticed the website didn't change the footer so I started checking in the local instance.
        Terminal was throwing a bunch of fun errors about "config value: extra" so I started looking into it and realized I didn't delete the separator below site URL:
        I decided to have a look around in the VSCode extensions and saw one called "Markdown all in one" which also came with a live-preview.
        Installed that and tested it. Seems to work perfectly. Displays images and everything.

    Continuing at home on my desktop machine. 

        Started by setting up VSCode like I already had on my laptop. Installing the Markdown Preview extension. 
        Always starting with git pull. Remember to navigate into the correct directory first:
            "cd ~/OneDrive/desktop/FabAcademy/git/magnus-petursson"

        Forgot to document it when it happened since I was almost too busy laughing. I navigated to the wrong directory, Got confused since git bash wasn't recognizing it and did another clone. This placed the repo inside itself and made OneDrive *very* confused. I'm not sure how or why but it nested folders within folders in a loop at least three deep. Moving the folder to a location where OneDrive doesn't interact with it completely solved the issue. Also made sure to delete the folder loop business.


        Got started on adding to the site. Created this wall of text and the one above. 
        Wrote a basic introduction.
        Played around with the separators in markdown. ## for headers, ``` for code blocks. > for block quotes. (Almost confused those with code blocks)
        Only playing around with things I can see in the site already. Used https://www.markdownguide.org/basic-syntax/ for reference.
        I'll do more reading on the documentation tomorrow. Definitely want to find a way to make these walls of text collapsible. I'll figure that out before the lecture tomorrow.
        I tried to comment out the bottom of the page. The Code Example and the Video segments. First time it worked in my real-time view in VScode but not on the fabacademy site. Testing if I formatted it improprerly. Markdown doesn't have proper comments so I'm trying to use HTML Style "<!---" and "-->" Hopefully this works.