Skip to content

1. Principles and practices, Project management

Overview of week 1 assignment

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

Project management

2. Git

Here is what I learned from the class and the following sources:
GitHub training
Wikipedia
Git Book (Japanese)
Qiita article (Japanese)

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 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)

3. Building my personal site

PC and OS I use:
- MacBook Pro 13”, 2020
- macOS Sequoia Ver. 15.2

Below is a list of the steps I took to build this site:
A. Setting up Git using Terminal
B. Setting up VS Code to edit MkDocs
C. MkDocs
D. Using template
E. Learning Markdown

A. Setting up Git using Terminal

Below are the basic terminal commands I learned:
Basics of Terminal (Japanese) 

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

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

git --version
git config --global user.name "naokihayashi"
git config --global user.email "my email"

b. Generate SSH key

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 modifying README.md and pushed the changes. 

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

I checked README.md on GitLab and it worked. Git setup done!

B. Setting up VS Code to edit MkDocs

Since I had already downloaded VS Code, I was able to open the local repository for this site, and I was able to open the project folder.

C. 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, I tried to install MkDocs according to MkDocs.
But I got the message “command not found”. 

pip install mkdocs
-bash: pip: command not found

Then, I checked if pip and Python are installed or not. 

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 Finally, I was able to successfully install pip and finally install MkDocs… 

pip install mkdocs

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

D. Using template

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

Theme “Material”

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

I could install “Material” theme using “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 you can change the settings by modifying it. I followed the Tips.

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

These articles were helpful to understand how to use it.
Markdown Syntax (Japanese)
Markdown and Markup (Japanese)

Material Theme

Thank you for your patience…!