Week 01: Principles and Practices, Project Management¶

Plan and sketch a potential final project¶

Final Project Image Autonomous pen plotter that draws line drawings on an unlimited surface with your preferred pen of choice. The robot knows its own position by scanning the environment with its camera eyes, so it can draw very precisely. As a hobby sewist, I want to use this little robot to copy sewing patterns, or as a weekend sumi-e painter, I want to copy my draft onto a very large paper with a water-erasable pen.

Assignements¶

plan and sketch a potential final project
download, read, and sign the student agreement,and commit the file to your repo
work through a git tutorial
build a personal site in the class archive describing you and your final project

Work Process Details¶

Step 1: Set-up Git¶

I went through the git tutorial on fabcloud. The first steps to use git are to install git and set your user name and email with the following commands.

git config --global user.name "myname"
git config --global user.email "my@email.com"

However, I knew that I already have git setup on my Mac, so I confirmed that with the following command.

git config --list

Step 2: Set-up SSH connection with gitlab.fabcloud.org¶

To use SSH, you need to type the following command.

ssh-keygen -t ed25519

Again, I knew I have an SSH key, so I confirmed and saw the key with the following command.

cat ~/.ssh/id_ed25519.pub

I added an SSH key to my profile of GitLab by going to Profile icon > Preferences -> SSH Keys -> Add new key. Then I verified that I have SSH connection with GitLab on fabcloud.org with the following command on the terminal.

ssh -T git@gitlab.fabcloud.org

GitLab, the remote origin, warmly welcomed me saying “Welcome to GitLab, @myname!”

Attention

Ensure you are pointing to gitlab.fabcloud.org. Connecting to the standard Gitlab.com will not work for your Fab Academy repository!

Step 3: Clone the Fab Academy student repository¶

I first cloned my Fab Academy 2026 student site with the following command.

git clone git@gitlab.fabcloud.org:academany/fabacademy/2026/labs/kannai/students/my-name.git

Step 4: Choosing Material for MkDocs¶

While the standard MkDocs is powerful, I found that Material for MkDocs has superior UI and UX.

Feature	HTML (Manual)	MkDocs	Material for MkDocs
Ease of Use	Low (Tag soup)	High (Markdown)	High (Markdown)
Search	None (Manual)	Basic	Advanced client-side search
Responsiveness	Manual Effort	Moderate	Perfect on Mobile/Tablet
Dark Mode	Manual Effort	Requires CSS	Native Toggle included
Visuals	Custom	Clean/Plain	Material theme

I installed the Material for mkdocs locally using:

pip install mkdocs-material

After I configured the repo referencing the official Material for MkDocs site and translating sample html files with Google Gemini, and came to the local session, I realized that there is a very detailed instruction by Tamiya-san, the instructor of Kannai, who kindly prepared sample mkdocs.yml with all the convenient plug-ins listed.

Important

Look up FabLab documents before you start assignments. There are a lot of hints there and it will save you trouble.

In the end, I copy-pasted mkdocs.yml and .gitlab-ci.yml in FabLab Kannai Site repository. Tamiya-san shared with me FabLab Kannai icon, which I proudly put on my site!

Step 5: Documentation Workflow¶

I created the weekly documentation template according to Rico’s lecture in the Student Bootcamp. I took a photo of my sketch using an app named Genius Scan so that we have a nice clean PDF as if it is scanned. I converted and resized the image to JPEG using Mac’s default Preview app.

Sketching: Hand-drawn initial ideas.
Scan: Use the Genius Scan app.
Convert to JPEG: Use the Preview app on Mac.
Linking images and writing up the contents in markdown.
Grammar check: Ask AI to check grammar and fix when necessary.

I am using the AI editor Cursor for the entire process. Cursor Screen

Step 6: Local Testing and GitLab Workflow¶

Before pushing my changes to the cloud, I always test locally to ensure the Markdown renders correctly and the navigation works as expected.

1. Launching the Local Test Server¶

MkDocs includes a built-in development server that allows you to preview your site. It features “Live Reloading,” meaning the browser refreshes automatically every time you save a file.

Run:

mkdocs serve

The terminal will provide a local URL, such as http://127.0.0.1:8000/, for me to check how it looks.

2. Pushing changes to Gitlab¶

Once the local preview looks good, I send the changes to the Fab Academy GitLab server.

# 1. Stage all changes (new images, .md files, and config changes)
git add .

# 2. Record the snapshot with a descriptive message
git commit -m "week01 documentation"

# 3. Upload to the server
git push

3. Verifying the Results¶

Once the pipeline passes, my site will be updated at my FabAcademy student URL. If not, I would go to the Pipeline page of GitLab, check the status and error message.

Checklist¶

[x] Sketched your final project idea(s)
[x] Described briefly what it will do and who will use it
[x] Made a website and described how you did it
[x] Created a section about yourself on that website
[x] Added a page with your sketch and description of your final project idea(s)
[x] Documented steps for setting up your Git repository and adding files to it
[x] Pushed to your class GitLab repository
[x] Signed and uploaded Student Agreement

Digital Files¶

Source Code