03.03.2025

1. Principles and Practices, Project management

view Checklists

Checklist personal:
- [ ] GPTcheck for better markdown
- [ ] compress all files before push

- [x] integrate S0 state of the page
- [x] link to S0 state of the page
- [ ] fix wrong Link screenshots

- [x] add learning section
- [x] install spelling check tool
- [x] embed images
- [ ] find automatic way to delete unreferenced files - [ ] auto OCR notes
- [x] extend and collapse parts
- [ ] insert links to socials
- [ ] grammar checker, DeepL integration
Checklist: Nueval: Student's checklist
- [x] Sketched your final project idea(s)
- [x] Described briefly what it will do and who will use it
- [x] Made a website and described how you did it
- [x] Created a section about yourself on that website
- [x] Added a page with your sketch and description of your final project idea(s)
- [x] Documented steps for setting up your Git repository and adding files to it
- [x] Pushed to your class GitLab repository
- [x] Signed and uploaded Student Agreement
Checklist: Task list Class/Nueval
Principles and Practices (part 1 of 2)
- [x] Plan and sketch a potential final project
Project Management (part 2 of 2)
- [x] Read, sign (add your name to) the student agreement and commit it to your repo
- [x] Work through a git tutorial
- [x] Build a personal website in the class archive describing yourself and your final project. Refer to the lecture material for examples.
- [x] Upload parts 1 and 2 to the class archive

You can find my student agreement here: student agreement

How to fix my website and why?

We are currently in week 6 and my workflow has been very slow so far. So it's a good idea to fix it before continuing with FabAcademy. What my current workflow was:

Documenting the process with simple .txt files
Save screenshots, media and photos to a folder
Send files to myself on Telegram to compress them
Download all files and rename them again
Insert everything in plain HTML text and place all images one by one
Push to git

Here is the old HTML version of my Week01

Shell/Terminal

What i would describe a shell as:
The so called shell is a command line tool that can access the underlying software of my computer. Before FabAcademy I had very little experience working the shell.
From now on I will reference the shell as Terminal, since I am on MacOS and the software is called Terminal.

Command	Description
`ls`	List files and documents in my current folder
`ls -a`	List all files including hidden `.files`
`cd`	Change directory to a new folder. Example: `cd Documents/FabAcademy_Git`
`cd ..`	Go one level up on your filesystem
`cd ~`	Go to my home directory
`mkdir`	Create new folder
`mv`	Rename folder: `mv "old folder name" "new folder name"`
`pwd`	Show current directory
`\`	Use backslash space (`\`) to reproduce a gap in a file name

Creating Terminal Aliases

Creating a Terminal alias was definitely necessary to quickly navigate to my FabAcademy folder.

open Terminal
Find out what shell version I am using: echo $SHELL
Add a .zshrc file to my User directory
Write my alias in the .zshrc file
Alias shortcut='command'

Important note: Without spaces in the filename, e.g: Google Drive should be written as Google\ Drive. No spaces are allowed between shortcut='command'.

MkDocks

What is MkDocs:

Source: official MkDocs user guide

My understanding of what MkDocs is:

lightweight software to 'convert' .md (Markdown) files into HTML files
load and develop web pages
can be themed with different templates
all configuration is stored in the .yaml file
free to use
requires Python

With that out of the way, I decided to set up MkDocs.

MkDocs needs Python. Jakob from our lab helped me with the setup. He recommended to use Python in a virtual environment.

Install MkDocs:

Source: official MkDocs installation guide

Install Python (jump to: Setting up and activating venv)
Install pip (jump to:Installing and upgrading pip)
Install MkDocs in your shell
pip istall mkdocs
check the version number of MkDocs
mkdocs --version

Setup MkDocs:

Source: official MkDocs setup guide

Before I did the MkDocs setup in my main folder, I tried it in a separate directory with a test folder!

Create a new project in the synced GitLab folder (replace my-project with your project name)
mkdocs new my-project
Go to the project directory
cd my-project
This will create a new MkDocs project is crated with the following folder structure

The docs folder will later contain my documentation source files. The first documentation file is already created and named 'index.md'. MkDocs has a dev-server that allows me to preview my documentation tasks as I work on it.
Start the dev server in the Terminal. Venv needs to be activated to run this command!
mkdocs serve
This server can be reached with: http://127.0.0.1:8000/ and supports auto-reloading. This allows live editing and automatic preview/rendering.
The Terminal window in which the server was started now serves as an information display for the current status of the server.

My personal MkDocs setup:

I decided to change my MkDocs theme to the Material theme. It is nice and simple and easy to navigate. Use pip install mkdocs-material to install the Material Theme. The theme needs to be enabled in the 'mkdocs.yml' file. Type theme: material in the head of the 'mkdocs.yml' document to change the theme.

For further customization I wanted to change a few parameters:
(changes must be made in the mkdocs.yaml file)
therefor I installed the YAML Language Support by Red Hat plugin.

This is the .yaml file of my test project:

The final step is to build the website using the terminal command
mkdocs build
This will create the finished HTML file, ready to be uploaded.

This is the site of my customized test project:

At this point, I felt confident enough to move the project to my main directory on my GitHub!

Documentation of upload still missing

Virtual Environments for Python

What is venv?

Source: Python documentation - venv

A virtual Python environment.
A secondary Python installation in a specific directory.
Isolates a specific Python version from the base Python version.
The venv folder is only for the Python version and not for project files.
venv is not considered movable or copyable (just create a new one).

Why use a virtual environment?

Using a virtual environment prevents different package managers from interfering with each other. However, this Python version needs to be activated every time you want to use it.

Setting up and activating venv

Currently, the venv environment is stored on my Google Drive and should not be moved to another location! I decided to make it available offline to avoid synchronization and Google Drive issues.

When I want to use the current Python version, I first need to activate it within the venv environment.

Steps to activate venv:

Open Terminal.
Navigate to the Fab Academy folder: sh cd path/to/FabAcademy
Navigate to the virtual environment: sh cd venv
Activate the virtual environment: sh source bin/activate
There should be a visual indication that venv is running: (venv) appears in front of the input line.

At this point, the virtual environment is active, and I can work with the Python version inside the venv folder.

Installing and upgrading pip

Install the pip package manager: pip install
If pip was installed automatically, upgrade it: pip install --upgrade pip
Check the installed pip version: pip --version

Markdown

Source: Markdownguide - basic syntax

Markdown is a simple formatting language that helps you format text as you type. Here are the main actions I use for my MkDocs documentation:

Basic Syntax

crate a line break with double space or the Html tag <br>
To separate Markdown items e.g headlines, lists and tables use Enter to start or end the Item

# Heading level 1

## smaller Headline

###### Heading level 6

**bolt** to crate bolt text

*italic* to crate italic text

Lists

Basic Lists

To crate a new list with numbers use 1. and 1.x.x

new structure
1.1 with subcategory

end the list by typing normal text.

To crate a new list with bullet use the - character

fist item
second item

Adding Elements in Lists

To add another element in a list while preserving the continuity of the list, indent the element four spaces or one tab, as shown in the following examples.

This is the first list item.
Here's the second list item.

I need to add another paragraph below the second list item.
And here's the third list item.

end the list by typing normal text.

This is a new list with numbers and

fist list item
second list item

here comes the indented Text 3. here is the third item, while keeping the structure of 1,2,3,4 ... working
new bullet point
new bullet point
list item

crate an Blockquote

Code

To implement a code use `code`

To implement a code block use triple `
here is an example for a codeblock:

Hi! I am a new code block 
with multiple lines

Tables

To build a table use a CSV to Markdown website!
My favorite is www.convertcsv.com

Images

To implement an image use
description

To embed an image with special properties, use HTML: <img src="drawing.jpg" alt="drawing" width="200"/>

Videos

To embed a video with special properties use HTML:

<video width="1080" controls autoplay loop muted>
  <source src="../media/week02/vid/show_parametric_18mm_comb.mp4" type="video/mp4">
</video>

This means: - .. → up from assignments/ to docs/ - media/week02/vid/show_parametric_18mm_comb.mp4 → down into the right folder

Links

To link to a certain website with a description text FabAcademy
To link to a certain website while displaying the actual link use
https://fabacademy.org/
Use relative file paths to link to another 'internal' site.
2. Computer-Aided Design

❌ WRONG:

✅ RIGHT:

Path	Description
`/media/img`	Absolute link to the root directory (do not use!)
`./media/img`	Relative link, pointing to a file in the same directory
`../media/img`	Relative link, navigating one level up

I have not used it so far:
tutorial for Social Cards

Tables

create a table in any spreadsheet software and copy the data into a csv. to md. converter.

ToDo lists

ToDo-list are essentially a normal list with boxes:

[ ] incomplete task
[x] completed task

Collapsible Sections

use this code:

<details>

<summary>Tips for collapsed sections</summary>


You can add text within a collapsed section.

You can add an image or a code block, too.

</details>

Note: The code between HTML brackets is treated as normal HTML code and will not react to Markdown formatting syntax
the rendered output looks like this:

Tips for collapsed sections

You can add text within a collapsed section. You can add an image or a code block, too.

VSCodium

Shortcuts

previewing/rendering the .md file CMD+SHIFT+V
open command palate CMD+SHIFT+P
replace multiple occurrences of a string (aka fix image links)
- open search window CMAD+F
- replace single or all occurrences
multi-cursor
- place multiple with mouse ALT+Click
- place multiple with Keyboard ALT+CMD+Arrowkeys
Column (box) selection
- text selection Box 'style' SHIFT+ALT

Plugins

Past Image by mushan

this plugin allows me to take a screenshot during my 'document as you go' process and pasting it right into VSCodium.

Install

In the extensions Tab in VSCodium type in the name of the plugin: Past Image and install it.

Setup/Configuration

The configuration of how the file should be called and where it will be stored is defined in the /.vscode/settings.json file.
Fist I started to read the documentation of the plugin, but after a while i decided to ask ChatGPT to configure the file for me. I helped me a lot to find the file in the fist place and to understand how to edit it.
These are some of my pompts I typed into GPT:

write a new file that gives every inserted file the name of the time and date as well as to which week it is assigned.
e.g week02_dateandtime

After a couple iterations I got what I wanted. Next time I would try to feed the documentation to ChatGPT directly via file upload instead of relying on a possibly outdated database. Some might say [RTFM](https://en.wikipedia.org/wiki/RTFM), others FTMTGPT - feed the manual to GPT.

This is my current settings.json file:

{
  "pasteImage.path": "${currentFileDir}/media/${currentFileNameWithoutExt}/img",
  "pasteImage.insertPattern": "![](media/${currentFileNameWithoutExt}/img/${imageFileName})",
  "pasteImage.basePath": "${projectRoot}",
  "pasteImage.namePrefix": "${currentFileNameWithoutExt}_",
  "pasteImage.nameSuffix": "",
  "pasteImage.timeFormat": "YYYYMMDD_HHmmss"
}

Use

Take a screenshot with:

SHIFT+CMD+CTRL+4 Take section screenshot directly to the clipboard
SHIFT+CMD+CTRL+3 Take fullscreen screenshot directly to the clipboard
SHIFT+CMD+5 Take a window screenshot
open the screenshot, copy
- to remove the shadow of the window, press
  SHIFT+CMD+5 and then alt to disable the shadow

Paste the image to VSCodium with:

ALT+CMD+V

Do not use the siple paste, it puts the picture in the wrong filepath!

YAML Language Support by Red Hat

Install auto completion for YAML syntax in VSCodium

in the menu bar go to: View -> Extensions
enter YAML
Install the Yaml language support from Red Hat

Code Spell Checker

a simple tool that does some very basic spelling checks

in the menu bar go to: View -> Extensions
enter Spell Checker
Install the Spell Checker

Git

How to setup Git

Install Git in Terminal with
brew install git
Check which git version is now installed with
git --version
Find your global username in git
git config --global user.name
git config --global user.email

Now I asked ChatGPT “How do I create a local folder for Git and how do I use the ED255 keys?”
At this point I realized that I can't navigate file systems in the terminal. So I started learning the basics in the Terminal

After creating my folder, I went back to GPT and asked again: "How do I use the ED255 keys?"
Now many errors appeared and my computer couldn't connect to GitLab because of some problems with the public key. I ran the debug information and pasted it into my GPT:

ssh -vT git@gitlab.com

It didn't help :/. Then I decided to google and get a proper tutorial from GitLab's official documentation:
GitLab

... and I found the bug:
"replace gitlab.example.com with your GitLab instance URL:"
So I have to use:
git@gitlab.fabcloud.org

Now everything is fine and I got the message “Welcome to GitLab”! Perfect!
I cloned my repository to my assigned Git folder which I had moved to Google Drive for convenience at this point. Now I had all the information from my Git cloned to my local repository! Time to edit some files!

How to use Git

Back in my visual GUI, I was happy to edit my about.html file. I added the paragraph:
“If this is published on GitLab I understood how to use git.”

git status

did not give me any status back. I asked GPT: I am in the terminal, in the directory where I cloned my git. There I have modified my about.html file and now I want to push it to my online repository.

I always get the following error:
Serious no Git_repository (or any of the parent directories): .git.
After reading the description, I realized that I needed to navigate down one level to see the .git file.
Now it was time to use it:

Command	Description
`git status`	Get current status
`git add`	Add a file to your staging area
`git commit`	Start a commit
`git commit -m`	Adds a message in the end that labels the file
`git push`	Push the commit to the GitLab cloud

This is proof that I understand how to use the basic tools. Pretty satisfying to be honest!

What I learned form week01

better do things right the first time instead of having to do them again
websites HTML and Markdown are no mystery anymore
compressing and embedding images one by one is tedious
chatGPT is only helpful in solving concrete problems if you have an approximate understanding of the subject matter

1. Principles and Practices, Project management

How to fix my website and why?

Shell/Terminal

Basic navigation

Creating Terminal Aliases

MkDocks

What is MkDocs:

Install MkDocs:

Setup MkDocs:

My personal MkDocs setup:

Virtual Environments for Python

What is venv?

Why use a virtual environment?

Setting up and activating venv

Steps to activate venv:

Installing and upgrading pip

Markdown

Basic Syntax

Lists

Basic Lists

Adding Elements in Lists

Code

Tables

Images

Videos

Links

Social Cards

Tables

ToDo lists

Collapsible Sections

VSCodium

Shortcuts

Plugins

Past Image by mushan

Install

Setup/Configuration

Use

YAML Language Support by Red Hat

Code Spell Checker

Git

How to setup Git

How to use Git

What I learned form week01