Week 1 Assignments
- Student Agreement
- Work Through a Git Tutorial
- Build a Personal Site, with content
- About me
- Final Project Ideas
Student Agreement
The student agreement is committed to the git repository as part of the personal site in the "About" section.
Git and GitLab Overview
Git
Git is a so called "version control system." It can be thought of as a fancy version of "track changes" that you see in document software like Microsoft Word or Google Docs. However, Git can manage larger projects and keep track of many different files. All of the files for a given project are managed as a single "repository" for the project. Like track changes, Git keeps track of edits and updates - who changed what when. And if different people change the same thing in a conflicting way, Git can help to resolve the difference.
GitLab
Git can be run on an individual computer to manage files. But in order to collaborate or share content with other people, it needs to run on a shared service that is accessible online. GitLab is software that provides an online environment for using Git services. It is similar to how a web server enables a person or organization to make a web site available online, and it can be set up by individuals or organizations. GitLab enables an organization, such as the Fab Academy Program, to set up an online service for participants to use Git in order to manage their projects. Each participant is set up with an individual Git repository for their own project. In addition to managing the project content using Git, GitLab provides additional features for communication between participants and for web services to show repository content as web pages online.
Git / GitLab Setup
The Fab Academy progam uses Git to manage participant documentation and provides Git services using a GitLab environment for participants.
Connection to Fabcloud GitLab Site
For the start of the program, Fab Academy provides access credentials for the Gitlab service using the centralized Fab Cloud service for the program. My repository is at:
https://gitlab.fabcloud.org/academany/fabacademy/2025/labs/unccharlotte/students/david-wilson/
In order to access the Gitlab site, it is necessary to log in. This is done with the centralized Fablabs.io credential, using the lower option: or sign in with > Fablabs.
Actual sign in is done using the centralikzed Fablabs.io credential.
Sign in brings you to your individual Gitlab dashboard.
Setting Up GitLab SSH Connection
While updates can be made to the site directly through the GitLab web interface, it is generally more useful to use local programs, such as command line tools or coding IDEs.
In order to do so, it is necessary to set up a secure credential for those connections to use. This is done by generating a secure SSH access credential and adding it to your GitLab account. The SSH credential acts as a kind of password for connecting to your repository.
GitLab provides documentation on how to use SSH keys to communicate with GitLab. I followed the instruction steps for:
- Generate an SSH key pair
- Add an SSH key to your GitLab account
- Verify that you can connect
Generate an SSH key pair
To generate the SSH key pair, I used the command line terminal with the following command:
This generated a file containing the SSH credential that can be used use with GitLab. The output of the command looked like the following (specific details have been altered to preserve credential security):
> ssh-keygen -t ed25519 -C "<comment>"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/xyz/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/xyz/.ssh/id_ed25519
Your public key has been saved in /Users/xyz/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:vmO8eQWQxYn0ymQdj+123aBc987Def+ExOLw <comment>
The key's randomart image is:
+--[ED25519 256]--+
| ..**. |
| +=oZ o |
| =.= + + |
|..o * .. . . |
|.=+B * X . |
|..=o*. o o . |
| F oo ..+ .. |
| + .++. |
| ..o.== |
+----[SHA256]-----+
Add an SSH key to your GitLab account
In order to add the SSH credential to GitLab, I opened the Edit Profile menu option and selected the SSH Keys section.
Verify GitLab Connction
Once the SSH credential was added to GitLab, I tested to see whether the connection was working.
Git Workflow - Using Git with GitLab
There are several primary commands needed in using Git.
Clone
The clone command is used to make a copy of an existing Git repository, so that you can work with the content.
git clone git@gitlab.fabcloud.org:academany/fabacademy/2025/labs/unccharlotte/students/david-wilson.git
For example:
> git clone git@gitlab.fabcloud.org:academany/fabacademy/2025/labs/unccharlotte/students/david-wilson.git
Cloning into 'david-wilson'...
remote: Enumerating objects: 445, done.
remote: Counting objects: 100% (410/410), done.
remote: Compressing objects: 100% (392/392), done.
remote: Total 445 (delta 135), reused 0 (delta 0), pack-reused 35 (from 1)
Receiving objects: 100% (445/445), 14.14 MiB | 12.64 MiB/s, done.
Resolving deltas: 100% (148/148), done.
Pull
The pull command is used to make sure you are working with the latest copy of the repository content. If you were working on a team and someone else made changes, you would want to make sure you have those updates, before starting on your own. For example:
> git pull
remote: Enumerating objects: 7, done.
remote: Counting objects: 100% (7/7), done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 4 (delta 3), reused 0 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (4/4), 367 bytes | 91.00 KiB/s, done.
From gitlab.fabcloud.org:academany/fabacademy/2025/labs/unccharlotte/students/david-wilson
6323c16..9fe81a8 main -> origin/main
Updating 6323c16..9fe81a8
Fast-forward
public/about.html | 2 ++
1 file changed, 2 insertions(+)
Status
The status command is used to check the current status of the repository you are currently working in. For example, if I made a change to the about.html file, the status command would note it as modified:
> git status
On branch main
Your branch is up to date with 'origin/main'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: about.html
no changes added to commit (use "git add" and/or "git commit -a")
Add
The add command is used when you have made updates to the repository content and want to formalize those changes as part of the repository - either adding new files or editing existing files. For example, to note that I made an update to the about.html file that should be incorporated:
And I can check the status of the add:
> git status
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
modified: about.html
Commmit
The commit command is used to finalize changes to the working (local) repository content that have been staged with the add command. I can also provide a message to provide a general description of the changes.
> git commit -m "Revised the About page."
[main e4779e5] Revised the About page.
1 file changed, 1 insertion(+), 1 deletion(-)
Push
The push command is used to send committed changes to the working (local) repository back to the central GitLab repository online. Then changes that I have made locally can be seen and accessed by others who are viewing the repository on GitLab. For example:
> git push
Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Delta compression using up to 8 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 384 bytes | 384.00 KiB/s, done.
Total 4 (delta 3), reused 0 (delta 0), pack-reused 0
To gitlab.fabcloud.org:academany/fabacademy/2025/labs/unccharlotte/students/david-wilson.git
9fe81a8..e4779e5 main -> main
Work Through a Git Tutorial
I have previous experience with git. But it has been a while since I have used it regularly on a project. I worked through the following as a refresher.
- Initial connection to the Fabcloud GitLab site - using the web browser interface and fablabs.io credentials
- Checked git command line setup - usable git available in mac terminal
- Tested clone repository
- Took a little time to verify command line connection to GitLab. Git hosting environments may be set up in different ways, so it was not clear at the outset whether login credentials would support the connection. Confirmed with instructor that ssh setup was needed and proceeded with setup.
- Connection and initial clone worked fine with ssh setup
- Tested basic git operations for add, commit, push with command line
- Also tested branch / checkout operations
- Tested basic git operations within IDE - VS Code
- Regular use of git commands in creating the personal site
Build Personal Site in the Class Archive
I am fairly familiar with basic HTML development. I explored a variety of prevous student sites in order to get a sense for how things might be organized and takeaways for site design / building. I noted that a fair number of previous students had used the MkDocs static site building tool.
The idea of using markdown to focus a bit more on content seemed interesting, so I started to explore MkDocs for use in developing the personal site.
Setting up MkDocs
To make project content available online as web pages for browsing, it is helpful to format / structure the content as web pages. This could be done directly coded using HTML format for structure and formatting. For static documentation, it can be more straightforward to use a shorthand notation for web content, known as "markdown." For example, a header in markdown can use # My Header instead of the HTML <h1>My Header</h1>.
Writing documentation in markdown format can be more straightfoward, but the markdown still needs to be converted to HTML for presentation as a web page. MkDocs is a software program that is used to write documentation in markdown notation and convert the authored markdown version into HTML for display as web pages.
Python Install
MkDocs runs in Python, so a Python setup was needed for local development.
- Recent macs have a python installation (note that is accessed as
python3andpip3), but it is a little dated - Other primary options for install were using homebrew or the direct python installer
- I was a little wary of using a package installer (homebrew for mac programs) to manage another package installer (pip for python packages)
- I chose to do a direct install of Python
Python venv
It is still nice to maintain a clean environment. I was not certain what Python packages would actually wind up being used.
- I had noticed several ways that Python maintains different package environments - such as
venv,virtualenv, andpyenv. - These enable you to manage installed packages on a per-project basis
venvis packaged with recent Python versions, so I selected that one
A virtual environment is created by executing the venv module:
Once created, the environment is activated by invoking the /bin/activate command from where that environment was set up. This adds a tag to the start of the shell prompt as a reminder that the virtual Python environment is active. You can then deactivate to close the virtual environment. For example, I created one for MkDocs
[~/Documents/FabAcademy2025/gitlab-site/david-wilson]
> source ~/Documents/FabAcademy2025/python/venv/mkdocs/bin/activate
(mkdocs) [~/Documents/FabAcademy2025/gitlab-site/david-wilson]
>
... install / use mkdocs packages and functionality ...
(mkdocs) [~/Documents/FabAcademy2025/gitlab-site/david-wilson]
> deactivate
[~/Documents/FabAcademy2025/gitlab-site/david-wilson]
>
Using MkDocs Locally
With Python in place, I worked on setting up MkDocs. I tested the setup locally first on my workstation.
- I installed the packages for MkDocs (within the venv I had set up)
- I worked through the MkDocs getting started guide
- To practice on writing content in markdown instead of HTML, I translated the student HTML site provided on GitLab in the
publicdirecory into a MkDocs site
MkDocs provides a local web server, so that you can see the live updates in your browser as you go.
(mkdocs) [~/Documents/FabAcademy2025/gitlab-site/david-wilson]
> mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
WARNING - Doc file 'assignments/week01.md' contains a link
'../img/sample-photo.jpg', but the target 'img/sample-photo.jpg' is
not found among documentation files.
INFO - Documentation built in 0.15 seconds
INFO - [07:22:10] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [07:22:10] Serving on http://127.0.0.1:8000/
Using MkDocs with GitLab
Once I had the local version of MkDocs going reasonably well, I explored how to set up MkDocs with the Fab Academy GitLab platform. It took some time to understand the GitLab CI/CD process, in order to be able to set things up properly.
When you use git to send change(s) to GitLab, it triggers a series of processing steps on GitLab. The steps follow the instructions in the .gitlab-ci.yml file on the GitLab site. GitLab's CI/CD can do a lot of complex things to get things ready for update / deployment.
It took some time to understand the CI/CD process and what all the commands were doing, but I followed the
student-template-mkdocs Template
that had been used previously in Fab Academy. Once I understood it better, I tailored it a bit for my setup.
Using Material Theme with MkDocs
MkDocs comes with two default themes for documentation sites. But it also has some community developed themes. A popular theme that adds a lot of functionality is the Material for MkDocs theme.
- I set up and tested the Material for MkDocs theme locally
- Then made the updates needed to run with the GitLab CI/CD process and tested with the default MkDocs template site
Personal Site Content Development
Once MkDocs with Material Theme was set both locally and with GitLab, I was finally in position to do primary content updates for the assignments. This involved a fair bit of practice in using markdown, MkDocs and Material Theme capabilities, and git commands. The outcome is visible on the site, but highlights are:
- Developed general navigation structure for the site
- Tested out theming / configuration options
- Added content for primary assignment elements
- Student agreement
- Week 1 site development
- Final project ideas
Site Content
MkDocs enables authors to create content using "markdown" annotations for web page content formatting and structure. MkDocs provides a basic reference for Writing with Markdown.
For example, in order to create the bulleted list in the previous section, the Markdown syntax uses dashes and/or astrisks.
- Developed general navigation structure for the site
- Tested out theming / configuration options
- Added content for primary assignment elements
* Student agreement
* Week 1 site development
* Final project ideas
<ul>
<li>Developed general navigation structure for the site</li>
<li>Tested out theming / configuration options</li>
<li>Added content for primary assignment elements
<ul>
<li>Student agreement</li>
<li>Week 1 site development</li>
<li>Final project ideas</li>
</ul>
</li>
</ul>
Site Organization / Navigation Structure
MkDocs provides a basic framework for
structuring and organizing your web site. The site structure is defined in the mkdocs.yml configuration file. In order to organize my site, I edited the mkdocs.yml file with the following configuration for general information (site name / copyright detail), content structure and navigation.
In particular, the nav configuration organizes the site into sections that can navigated through the menu structure, as well as the specific markdown files that have the content for those sections.
site_name: David Wilson - Fab Academy
copyright: Copyright © 2025 David Wilson - Creative Commons Attribution Non Commercial
nav:
- Home: index.md
- About:
- About Me: about/about.md
- Agreement: about/agreement.md
- Assignments:
- Week 01: assignments/week01.md
- Week 02: assignments/week02.md
- Project:
- Idea: project/idea.md
- Final: project/final.md