Week 1 – Project Management

Fab Academy – Week 1

Date range: Week of 21st Jan

Instructor: Neil Gershenfeld

Project Management

🧠 Learning Objectives

• Identify and utilize version control protocol(s)
• Explore and use website development tool(s)

📋 Assignments

Individual Assignment

• [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.

Group Assignment

(If applicable)

🛠️ Tools & Materials

• Vscode
• Gitlab workflows extension for vscode
• Python
• mkdocs
• garpesJs and stitch by google

🧪 Process & Workflow

Step 1 – Setting Up an IDE

• I started reading about version control here: https://fabacademy.org/2024/recitation/version-control/#41
• I wanted to set up an IDE that would help me with web development as well as with other programming work like with python during the fab academy program. After some research I decided to use VScode and also use GitLab workflows extension for VSCode https://code.visualstudio.com/download

• In order to connect to your repository from VScode, there are two ways, either using SSH or Https, I found the latter to be easier and more straightforward.
• To connect vscode to you’re repository without having to put in your username and password, you’ll need to create a PAT (personal access token)
• From your repository on gitlab.fabcloud.org click on your avatar at the top right corner > Preferences> Personal access tokens > add a new token. To having any issues with this PAT I selected everything under select scope, click create token and copy your generated PAT

Here’s your token

• In vscode choose to login using a personal access token. From top search bar choose to enter url manually and enter gitlab.fabcloud.org, it will ask you to either generate a personal access token or enter one you generated previously:

Enter your email and your PAT

For more information you can look at these steps I followed here: https://forum.gitlab.com/t/use-of-private-gitlab-with-vscode/102454/2

if connected successfully you’ll see this message at the bottom of your vscode screen

You need to make a copy of your gitlab repository locally on your computer, from vscode command palette at the top type clone from Gitlab and choose your repo.

Then select your local repository directory:

Step 2 –Building the Pages

• I experimented with GrapesJS Studio to generate an HTML template using its AI feature. I used this prompt: "I want to create a template for my course assignments and final project, I want a menu to navigate to each week, a home page to give a brief about me. On each week's assignment page, I need the following sections (intro, steps and under each step pictures gallery, lesson learned, next plan)."
• The AI-generated output required significant effort to understand and clean up. I decided to keep it only for the first page as a landing page.
• For the weekly assignments and documentation, I'm using MkDocs. Since I depend heavily on Notion for note-taking and tracking my tasks, this approach makes it easier to export directly from Notion as markdown and drop it into the MkDocs docs folder on my website.

Step 3 –Setting up Mkdocs

• Download and install python. Make sure you choose to check the box that says “Add Python to PATH” during installation.
• Install mkdocs-material using vscode terminal. To make sure you have python installed, type:

python --version

Install Mkdocs

pip install mkdocs-material

• If you need a step by step video on how to install mkdcos, here’s a nice instructions video, it was very useful https://www.youtube.com/watch?v=s0d39k-IqN4
• When you install MkDocs, it creates a folder structure and a new index.md file. And when you push to the repo, this will replace your index.html, which was an issue in my case since I needed a custom landing page. For that reason, I had to rename the public folder to custom_landing and moved files in my repo to look like this:

my-repository/
├── custom_landing/
│   ├── index.html
│   ├── style.css
│   ├── (any other files or folders you need for your landing page)
├── docs/
│   ├── index.md
│   ├── weeks/
│   │   ├── week1
│   │   │   └── images/
│   │   └── week2
│   │   │   └── images/
├── mkdocs.yml
├── .gitignore
├── .gitlab-ci.yml

• After you finish setting up your mkdocs and edit your documentation, and want to push to your online repo, you need to have special instructions for the git push. These instructions are explained in the .gitlab-ci.yml file. Which looks like this:

image: python:latest

pages:
  stage: deploy
  script:
    - pip install mkdocs-material # Use 'mkdocs' if you don't use material theme
    - mkdocs build --site-dir public/docs
    # 2. Copy all your custom landing page files to the root
    - cp -r custom_landing/. public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

• This file will install python and mkdocs. Then it will keep my custom landing page intact.

Weekly Process

• Now that I have everything set, I perform the following steps weekly:

  • Export my notes from notion in a zip file.

    

  • I find this to be very useful, since images will be exported in this folder so I can manage image sizes and resize them before I add them to my project. There are many image resizing tools, for me I personally prefer using the built-in windows image editor

    

  • Move the files to repo folder, locally or online, commit your changes and push them.

  • Edit my custom index.html manually to add the links to point to my documentation.

⚠️ Problems & Solutions

• I had to spend a lot of time to figure out how to keep a custom landing page, I solved it by creating the gitlab-ci.yml file, with some help from google gemini. I asked it to give me a step by step instructions to do this, and it even helped me figure out an error message related to a type.

🧩 Files

https://gitlab.fabcloud.org/academany/fabacademy/2026/labs/vujade/students/sarah-aldosary

📝 Reflection

• Since I’m familiar with html, I never explored other options thinking it would be safer to stick to what I know, but soon after, I realized that editing html would be a huge hassle, and I need to find a way streamline the process of documentation
• Using notion to dump all my ideas and track my progress is a great way to not miss anything, and not worry about formatting when documenting, I want to try automating this process, so may be I’ll look into RPA tools.