Week 01 Principles and Practices
Assignment
- [x] Read, sign Student Agreement the student agreement and commit it to your repo
- [x] Work through a git tutorial
- [x] Build a personal website in the class archive describing yourself and your final project. Refer to the lecture material for examples.
- [x] Upload parts 1 and 2, to the class archive.
Research & Planning - Website
I am very familiar with HTML but it can be very tedious to code without the proper IDE. I was intrigued by the mkdocs option. Dr. Taylor mentioned it in his presentation. I liked the results of a clean interface with minimal code, but at this point I wanted to stay with HTML.
Process
Step 1: Getting Started
I began by looking at prior years websites to get an idea of how the "About Me" and "Homepage" pages were constructed and how much content was included.
My next step was deciding how I wanted my pages to flow. I needed something that would be easy to update, organized and a user friendly navigation. I feel like I should concentrate on content and worry about the visuals and navigation at a later time, but I also feel like if I don't address it now it will be harder to redesign later.
Step 2: Design/Modeling
Day 1
I already had Visual Studio Code set up from previous work with python projects. I confirmed git was installed on my MacBook with the command git --verson.
I set my git identity
git config --global user.name "first last"
git config --global user.email "NotGoingToMakeit@public.com"
Verify:
I logged into Gitlab using my fablab credentials and created ssh keys by following Gitlab's documentation to add to the gitlab repo.
After I created my ssh keys, I copied the public key to Github:
- Log into gitlab.fabcloud.org
- Click on your avatar
- Click on preferences
- Click on SSH Keys and add the new key.
I added a second key for my personal laptop.
Rule of thumb with SSH keys: Never give your private key to anyone. Only your public key is safe to hand out
Once I created the keys I ran the following command:
I cloned the repo using the following commands:
cd ~/
git clone git@gitlab.fabcloud.org:academany/fabacademy/2026/labs/charlotte/students/kimberly-alexander.git
cd kimberly-alexander
I initially started my design with the template provided by Fab Academy. My thinking was not to reinvent the wheel and just move as quickly as possible. I wanted to change the theme color and make a few minor changes. My colleague, Camille, was working on mkdocs. I liked the design she created, but I wanted to keep moving forward with HTML since I was not comfortable with mkdocs.
Day 2
I was not happy with my progress so I decided to integrate
HTML with mkdocs. Now I must research mkdocs. 
Day 3
I eventually went back to a simple web design with mkdocs with the material theme. Below are the steps I used to setup my site and add mkdocs to the project. I referenced Dr. Taylor's Google Site and also asked Claude AI for instructions as well.
- Created a new folder called fab-academy (mkdir fab-academy)
- Changed directories (cd fab-academy)
- Created a new virtual environment (python3 -m venv venv)
- Activated the environment (source venv/bin/activate)
- Installed mkdocs and mkdocs material (pip install mkdocs mkdocs-material)
mkdir fab-academy
cd fab-academy
python3 -m venv venv
source venv/bin/activate
pip install mkdocs mkdocs-material
Git Tutorial:
I copied the subtitles from the Version Control and GitLab recitation and pasted it into Claude AI. It created a document that I reviewed and discovered I didn't have the CI pipeline configured correctly with my mkdocs setup.
I overwrote my existing .gitlab-ci.yml file with code below:
image: python:latest
pages:
script:
- pip install mkdocs mkdocs-material
- mkdocs build --site-dir public
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
I had to run the following commands to get the public folder back to the proper state. since I had previously ran "mkdocs build" and then pushed the changes to the gitlab site.
# Create or edit .gitignore
echo "public/" >> .gitignore
# Remove public/ from Git tracking (but keep local copy)
git rm -r --cached public/
# Commit these changes
git add .gitignore
git commit -m "Let CI build public folder instead of committing it"
git push
After these changes, I am now back in business.
To summarize, I made the website with Visual Studio Code, mkdocs, mkdocs material, ChatGPT created the "Let's Go", along with Photoshop to compress the images. I asked Claude AI to create a reference page for mkdocs for future reference.
What worked, what didn't, adjustments made...
Initially learning the syntax of mkdocs was a little challenging. I didn't realize that spacing could cause issues especially in the navigation structure. I'm not sure what I did wrong, but at one point I could not get the yml file to "like" the indentation I put in. I'm assuming I had an extra space or tab, but I ended up pulling old code and copying and it worked after that.
There are a lot of features within mkdocs that make documentation simple. The themes, navigation and table of contents are just a few of the features that mkdocs has to offer.
What Worked Well Mkdocs is a great tool. Within a few days of use I was feeling comfortable with it. I understand the power of git as well and look forward to utilizing in other projects.
Results
Final Output
The final result is this website. I know there will be more tweaks to it, but for now I am happy with the result and ease of use.
| File | Description |
|---|---|
| Student Agreement | Student Agreement |
| MkDocs Summary | MkDocs Summary |
| MkDocs Chat History | MkDocs chat history |
Reflection
What I Learned
I learned I really enjoy working with mkdocs so i can focus on documentation and not website design.
What I Would Do Differently
I should have stopped modifying the website design a day ago. Time management is going to be an issue if I don't learn to move on.
Time Spent
I didn't document time for this assignment, but going forward I will start recording time.