2. Project management

This week I worked on defining my final project idea and started to get used to the documentation process.

Git and Version Control

To manage my project files and documentation, I used Git for local version control and GitLab as the remote repository.

• Git is a distributed version control system. It runs on my local computer and tracks the entire history of changes to my files. Every time I save a new version of my project (a commit), Git takes a snapshot of all the files, allowing me to revert to any previous state if needed.
• GitLab is a web-based platform that hosts Git repositories. It serves as the central, cloud-based location for my project. Beyond just storing code, GitLab adds powerful collaboration features like Merge Requests, issue tracking, and, crucially for this course, Continuous Integration/Continuous Deployment (CI/CD) pipelines to automatically build and publish my website.

Analogy: If Git is the engine of a car (the core technology), then GitLab is the entire garage, complete with tools, a team of mechanics, and a showroom to display the finished car.

Setting Up Secure Access with SSH Keys

To securely connect my local computer to GitLab without entering a password every time, I generated a public/private key pair.

• Private Key: This remains securely stored only on my computer. It acts as my personal, secret identity card. I never share this key.
• Public Key: This is the “lock” that corresponds to my private key. I uploaded this to my GitLab account’s settings.

Why is this necessary? Using SSH keys is more secure than passwords because the private key never travels over the network. It allows Git on my computer to automatically and securely authenticate with GitLab for operations like git push and git pull.

I generated the key pair using Git Bash with the command:

ssh-keygen -t rsa -C "hoangkhai2626@gmail.com"

My Git Workflow Explained

Here is the step-by-step process I use to update my website, with a clearer explanation of what each command does:

1. Fork & Clone: I started by forking the Fab Academy Oulu template repository on GitLab to create my own copy under my account. I then cloned this forked repository to my local machine using the SSH URL: bash git clone git@gitlab.com:KhaiNguyen2626/students_template_site.git This command creates a local folder on my computer that is linked to my remote GitLab repository.

2. Making Changes: I open this local folder in VS Code to create and edit my documentation files.

3. git status: This command does not update anything. Instead, it shows me the current state of my local repository. It lists any files I have modified, added, or deleted that are not yet part of a tracked snapshot (commit). It’s a way to check what has changed before I decide to save those changes.

4. git add <file>: This command does not store anything permanently yet. It tells Git, “Please include the changes from these specific files in my next snapshot.” It places the changed files into a “staging area,” preparing them for a commit. For example, git add images/pic.jpg week2.md stages two specific files.

5. git commit -m "Meaningful message": This is the command that finally stores the changes in my local repository. It takes all the files I’ve staged with git add and creates a permanent snapshot (a commit) with a unique ID. The -m flag allows me to add a short message describing what I changed (e.g., "Added project concept and week2 documentation").

6. git push origin main: This command uploads all the commits I’ve made locally to my remote repository on GitLab (origin). This syncs the online version of my project with the work I’ve done on my computer.

Generating the Website with MkDocs

My website is not built manually with HTML. Instead, it is automatically generated using a Static Site Generator called MkDocs.

• Static Site Generator (MkDocs): This is a tool that takes simple text files written in Markdown (like week2.md) and a configuration file (mkdocs.yml), and converts them into a full, navigable HTML website. This means I can focus on writing content in a simple format without needing to be a web developer.

• Markdown: This is a lightweight markup language with an intuitive syntax. MkDocs converts my Markdown files into the corresponding HTML. For example:

  Markdown Syntax	Rendered Output (on Website)
  # Heading 1	Heading 1
  ## Heading 2	Heading 2
  **Bold Text**	Bold Text
  - List item	• List item
  [Link Text](url)	Link Text
  	Renders the image

Configuration Files

Two key YAML (.yml) files control how my site is built and published:

1. mkdocs.yml: This is the main configuration file for MkDocs. It defines the structure and style of my website. I modified this file to set my site’s name, change the color theme, and define the navigation menu (e.g., which pages appear in the top menu and in what order).

2. .gitlab-ci.yml: This file is the instruction set for GitLab’s built-in CI/CD system. I did not need to modify this file. It automatically tells the GitLab server: “Every time KhaiNguyen2626 pushes new changes to the repository, please run the mkdocs build command to generate the static HTML website and then publish it to GitLab Pages.” This is the automation magic that brings my site online after every git push.