Week 01a - Project Management

This week we have the following tasks to complete:

• Learn how to use Git
• Build a personal website
• Describe yourself
• Read and sign the student agreement
• Commit to my repository

How to Use Git?

Everything started with our GitLab repository and the provided template. The first step was to focus on what I had and how to use it. What did I have? A basic website with numerous examples of how to integrate different types of text, pictures, videos, and links. For this, I used GitLab’s Web IDE, which also helped me get more familiar with Git. The next step was figuring out how to clone my repository to my local PC. I followed the git help page and received additional guidance from our local instructor, Ferdi. This Git tutorial provided an excellent summary of the concepts we learned.

Before I could use git on my PC, I needed to install it. Once installed, I opened Git Bash from the folder where I wanted my cloned repository. To configure Git, I had to connect my client to my account using the following commands in the Git Bash command line:

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

Next, I needed to generate an ed25519 SSH key. I followed the instructions from the git help page. To generate the key, I used this command in the Git Bash window:

ssh-keygen -t ed25519 -C "your@e-mail_adress.com"

I copied the key with this command:

cat ~/.ssh/id_ed25519.pub | clip

I then connected this key to my GitLab account by navigating to Edit Profile --> SSH Keys --> Add New Key, pasting the key, setting a title, and clicking "Add Key."

Normally, I use VS Codium’s built-in buttons to push/pull my repository. However, when something doesn’t work as expected, I rely on the following Git Bash commands. Always ensure you’re in the correct directory before executing them:

git status                              # Shows which files were edited, added, or deleted
git add .                               # Stages all files for the next commit
git commit -m "your commit message"     # Adds a commit message
git push                                # Pushes the local repository to Git
git pull                                # Pulls files from Git to the local repository

Build a Personal Website

The first step in building my website was to clone the repository locally. To do this, I used the link under Code --> Clone with SSH and ran the following command in my Git Bash terminal:

git clone "use ssh link from git"

Next, I opened my editor of choice (in my case, VS Codium) and opened the local folder I had selected earlier. For my website, I decided to use MkDocs, a static site generator, along with the Dracula theme. To use MkDocs, I needed to install Python. For convenience, I also installed the VS Codium Python extension. To install MkDocs and the theme, I used the following commands in the VS Codium terminal:

pip install mkdocs
pip install mkdocs-dracula-theme

I followed the installation guidelines and instructions provided by MkDocs, I referred to the the official documentation on the Dracula theme page for theme-specific installation.

How to Use MkDocs?

The provided template was plain HTML with minimal CSS, requiring manual updates in HTML terms. MkDocs, on the other hand, uses Markdown—a simpler, more intuitive language. While Markdown occasionally uses different syntax for features like bullet points, it is far easier to work with than raw HTML.

To get started, I created a new MkDocs project using the following commands in my VS Codium terminal:

mkdocs new my-project
cd my-project

This process generated an mkdocs.yml file, which defines the website configuration. To change the website name displayed in the top-left corner, I updated the following string:

site_name: your website name

To use the third-party Dracula theme, I added this section to the configuration file:

theme:
    name: dracula

To create a navigation bar, I added:

nav:
- subpage name: subpage_name_file.md

I then created a new file with the corresponding name in the docs folder.

For development purposes, MkDocs includes a local development server, accessible at 127.0.0.1:8000 in your browser. This server refreshes automatically whenever changes are saved, making it a convenient development tool. To use it, execute the following command in the terminal:

mkdocs serve

Adding links in Markdown is straightforward:

[Link text](URL)

Adding images is similar:

![Image Title](relative_path_to_docs/name.png)

However, I encountered a problem with image alignment and inconsistent sizes. Markdown does not natively support alignment parameters, so I installed the Markdown Attribute List plugin. Details and other helpful extensions can be found here. To use the Attribute List plugin, I added it to the mkdocs.yml file:

markdown_extensions:
    - attr_list

With this plugin, I could add alignment parameters to images, such as:

![Image title](dir_related_to_docs/name.png){align=left}

To enable additional customization, such as centered alignment, I installed the md_in_html extension and added it to the extensions list:

markdown_extensions:
    - md_in_html

Using this extension, I could mix HTML and Markdown. For example, to center an image, I used:

<center>
    ![Image title](dir_related_to_docs/name.png){width="300"}
</center>

This approach also allowed me to set width and height parameters for images.

How Do I Publish My MkDocs Files?

here are multiple ways to publish MkDocs files. I chose to use GitHub Actions for automation. The Material theme documentation. provided excellent guidance. Other methods include manual publishing via MkDocs, but automation saved time for other tasks. To experiment, I initially used Henk’s files the way they are. Later, I replaced his files with my own MkDocs files, retaining only his requirements.txt and gitlab-ci.yml files. However, this setup didn’t work.

Why didn’t it work? Henk’s files referenced the Material theme, while I initially planned to use the Dracula theme. Upon closer inspection, I found that Henk’s gitlab-ci.yml file linked to the requirements.txt, which pointed to the Material theme. Since I couldn’t easily edit this link in VS Codium, I decided to switch to the Material theme temporarily by installing it and updating my mkdocs.yml file. The process was similar to the Dracula theme setup. For further information, visit the Material for MkDocs getting started page.

During Neil’s lecture, where some students presented their assignments for comparison, I noticed that Kerstin from Bottrop had also used the Dracula theme. Curious about her approach, I investigated further and found that the implementation was surprisingly straightforward—I simply needed to add the following line to the requirements.txt file:

mkdocs-dracula-theme

Initially, I was confused because hovering over the commands in this file displayed what appeared to be hyperlinks. However, I couldn’t identify any specific syntax for manually inserting a hyperlink. I had encountered this before but didn’t consider that it could be this simple. As it turns out, Git handles this automatically—just adding the command to requirements.txt is sufficient, and the necessary dependencies are resolved without additional configuration.

What caused problem?

While describing my potential final project, I encountered the error: "Error: Config file 'mkdocs.yml' does not exist." This occurred after I temporarily switched the theme to Material. The issue was caused by being in the wrong directory—I was one level above the correct folder in the hierarchy.

What Did I Learn This Week?

Key takeaways from this week include:

• Proper usage of Git
• Building a website using MkDocs

What Do I Want to Improve Next Week?

I aim to enhance my documentation workflow by taking more screenshots to avoid recreating situations unnecessarily.

To create this page, I used ChatGPT to check my syntax and grammar.

Copyright 2025 < Benedikt Feit > - Creative Commons Attribution Non Commercial

Source code hosted at gitlab.fabcloud.org