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.
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
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
python3
andpip3
), 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
venv
is 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
public
direcory 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