Skip to content

03.03.2025

Project management

view Checklists *Checklist personal:*
- [x] install spelling check tool
- [x] embed images
- [ ] find automatic way to delete unreferenced files - [ ] integrate S0 state of the page
- [ ] link to S0 state of the page
- [ ] add learning section
- [ ] auto OCR notes
- [x] extend and collapse parts
- [ ] insert links to socials
- [ ] grammar checker, DeepL integration

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:

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

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.

Creating Terminal Aliases

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

  1. open Terminal
  2. Find out what shell version I am using: echo $SHELL
  3. Add a .zshrc file to my User directory
  4. Write my alias in the .zshrc file
  5. 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

  1. Install Python (jump to: Setting up and activating venv)
  2. Install pip (jump to:Installing and upgrading pip)
  3. Install MkDocs in your shell
    pip istall mkdocs
  4. 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!

  1. Create a new project in the synced GitLab folder (replace my-project with your project name)
    mkdocs new my-project

  2. 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.

  3. start the dev server
    mkdocs serve
    This server can be reached with: http://127.0.0.1:8000/ and supports auto-reloading. This allows live edeting and automatic preview/rendering.

  4. 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:

  1. Open Terminal.
  2. Navigate to the Fab Academy folder: sh cd path/to/FabAcademy
  3. Navigate to the virtual environment: sh cd venv
  4. Activate the virtual environment: sh source bin/activate
  5. 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

  1. Install the pip package manager: pip install
  2. If pip was installed automatically, upgrade it: pip install --upgrade pip
  3. 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

  1. 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

  1. fist list item

  2. second list item

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

  3. new bullet point

  4. new bullet point
  5. 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 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

Social Cards

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

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

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