Skip to content

1. Principles and practices, Project management

Overview of week 1 assignment

  1. Principles and Practices
    • Plan and sketch a potential final project: I posted it at Projects.
  2. Project Management
    • Read, sign the student/instructor/lab agreements, and commit to your repos: Completed and committed to my repos.
    • Work through a git tutorial
    • Build a personal site in the class archive describing you and your final project

Project management

1. Git

Here’s what I learned from the class and the following sources:

Git was created in 2005 by Linus Torvalds, who also created the Linux operating system, and was named after the British slang for an "obnoxious person" or a "stupid/annoying person.”

Important terms and Git concepts:

  • Repository (Repos): A project’s folder that Git tracks, containing files and history
  • Branch: A separate line of work within the project
  • Main: The primary and stable branch of the repository
  • Remote Repository: The shared version of the repository, hosted online (in this case, GitLab)
  • Origin: The default name for the remote repository
  • Commit: A snapshot of changes saved in the repository
  • Push: Sending changes from local repository to the remote
  • Pull: Getting the latest changes from the remote repository to local
  • Merge: Combining two branches into one
  • Pull Request (PR): A request to review and merge a branch into another (commonly main)

Sources:
GitHub training
Wikipedia
Git Book (Japanese)
Qiita article (Japanese)

2. Building my personal site

PC and OS I use:

  • MacBook Pro 13", 2020
  • macOS Sequoia Ver. 15.2

Here is a visual diagram and a list of the steps I took to build this site:

A. Setting up Git using Terminal
B. Setting up VS Code for MkDocs
C. Installing and Configuring MkDocs
D. Using a Template
E. Learning Markdown

Git

A. Setting up Git using Terminal

Below are the basic terminal commands I learned: Common Terminal Commands.

Up/Down arrows : Reuse previous commands from the history
ls : Displays files and directories in the current directory
ls -la : Displays detailed information for all files and directories, including hidden ones
cd : Change directory
cd ~/ : Moves to the home directory
cd .. : Moves to the parent directory
open . : Opens the current terminal directory in Finder (macOS only)
pwd : Displays the path of the current working directory
mkdir : Creates a directory

Git related terminal commands:
git add . : Add changes
git commit -m"commit message" : Commit changes, add "commit message"
git push : Push changes
mkdocs serve : Launch a local MkDocs server (for preview locally)

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.63 seconds
INFO    -  [19:56:50] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [19:56:50] Serving on http://127.0.0.1:8000

Preview it in a browser using http://127.0.0.1:8000.
Ctrl + C to exit mkdocs serve command

a. Check Git version, set user name and e-mail:

git --version # Check Git version
git config --global user.name "naokihayashi"
git config --global user.email "my email"
b. Generating SSH key for GitLab

This is to ensure that the connection between GitLab and my computer is secure and no one can edit my site except me. This method uses a public key stored in GitLab and a private key kept on my computer to identify and authenticate each other.

ls --la #Display all files including hidden ones to check the SSH folder
cd .ssh #move to the SSH folder
ssh-keygen -t ed25519 #Generate SSH key
pbcopy < id_ed25519.pub #Copy "id_..." to clipboard
c. Set the SSH key to my GitLab
I pasted the key into my GitLab:
User settings > SSH Keys > Add new key
Setting SSH key on GitLab

d. Clone with SSH
I created a repository folder on my computer and copied "Clone with SSH" to my clipboard.

git clone git@gitlab.fabcloud.org:academany/fabacademy/2025/labs/kannai/students/naoki-hayashi.git
Clone with SSH

Then I tested if it worked by committing README.md, pushed the changes and confirmed that README.md in GitLab.

git add . #Add changes
git status #Check status (e.g., changes)
git commit -m"comment" #Commit changes and write "comment"
git push # Push changes

B. Setting up VS Code for MkDocs

Since I had already downloaded VS Code, I could opened my local repository.

C. Installing and Configuring MkDocs

"MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introductory tutorial, then check the User Guide for more information." MkDocs

Problems I faced while installing Mkdocs

pip command not found
Initially, followed the MkDocs but encountered an issue below: 

pip install mkdocs
-bash: pip: command not found

"pip" in Python is a package manager that allows you to install, manage, and update various Python packages.

I checked if pip and Python are installed.

pip --version
-bash: pip: command not found
python3 --version
Python 3.9.4
Python was installed but pip was not. So, I tried to install pip.
I downloaded the get-pip.py, change directory to the download folder, and run the command.
python get-pip.py ...Not worked, so changed to "python3"
python3 get-pip.py ....Worked!
pip install mkdocs ...I was able to successfully install pip and finally MkDocs!

pip install

D. Using template

I downloaded Student template MkDocs, moved the all files (including hidden ones) to my local repository, and pushed them to GitLab.

Material Theme

Mkdocs Material is a theme for MkDocs inspired by Google's Material Design principles. Material for MkDocs

Initially, I did not have the Material theme installed, but I should have installed it earlier.

mkdocs serve
ERROR   -  Config value 'theme': Unrecognised theme name: 'material'. The
           available installed themes are: mkdocs, readthedocs

To fix this, I used "requirement.txt"

requirement.txt is a text file that lists the packages and their versions that your Python project requires.

pip install -r requirements.txt
MkDocs contains a YAML configuration file, and I can change the settings by modifying it. I followed the Tips but only changed the color and the font. 

theme:
  palette:
    primary: white
  font:
    text: Roboto

E. Learning Markdown

I am new to Markdown so I learned what it is and how to edit a site based on a template.

Markdown is a lightweight markup language used to format plain text into structured text, often converting it into HTML. It was created by John Gruber in 2004. The name "Markdown" comes from the idea of "marking" up text to add structure, with a focus on being easy to read and write. It’s designed to be simpler than traditional HTML. Wiki

The site was helpful to understand how to use it markdown-it.

Material Theme

Thoughts

Since I was new to almost everything, Git, Terminal, MkDocs, pip, Markdown... I initially felt overwhelmed and unsure of what I was doing. However, by tackling each step one at a time, I gradually built confidence, at least enough for learnning. Thank you for your patience...!