Skip to content

Principles and Practices

Assignment

  • Read, sign the student/instructor/lab agreements, and commit to your repos.
  • Work through a Git tutorial.
  • Build a personal site in the class archive describing you and your final project.

Setting Up the Website on the Fab Cloud

Instructions and Theme

I followed these 🇮🇸 instructions provided by my pre-fab instructor Svavar Konráðsson, which were very helpful in setting up MKDocs. MKDocs is a static site generator that uses Markdown. There are numerous themes available, but I decided to use the Material theme.

To get started, I downloaded the following tools:

VS Code Extensions

In VS Code, I recommend installing Python, Markdown Extension Pack, and YAML. YAML requires a bit more setup to work with MKDocs, which you can find instructions for here inside of the note: Recommended: configuration validation and auto-complete.

After installing these tools, I started by connecting VS Code and Git to my GitLab account. To log in with Git, I needed to open up the terminal and type:

git config --global user.name "name"
git config --global user.email "email@example.com"

Next, I went to The Fab Cloud. Then I went into my settings by pressing my profile picture and then preferences. Then I went into the SSH Keys section and used my password manager (1Password) to create an SSH key. I could also have created a key with this command in the terminal:

ssh-keygen -t ed25519 -C "<comment>"

I created a repository on The Fab Cloud, which will store my project and host the website. Next, on my machine, I created a folder named 'Code' on my C: drive. Within the 'Code' folder, I created a subfolder to store the website files during development.

Inside this folder, I cloned my Fab Cloud repo using this command:

git clone git@gitlab.fabcloud.org:academany/fabacademy/2025/labs/vestmannaeyjar/students/bjartur-hlynsson.git

After completing the setup, I opened VS Code, navigated to the 'Code' folder, and selected my project folder. I deleted everything to start from scratch with mkdocs. So next, i needed to install MkDocs, so I opened the terminal and typed:

pip install mkdocs-material

This command installed all the necessary dependencies. Afterwards, I typed:

mkdocs new .

This command created a folder containing all the required resources for MKDocs, which looked like this:

├─ docs/
│  └─ index.md
└─ mkdocs.yml

When all that was done, I went into the mkdocs.yml file and typed:

site_name: Bjartur's Fab Academy Journey

theme:
  name: material

This told MKDocs I wanted to use the Material theme. To check everything was successful, I went into the terminal and typed:

mkdocs serve

Then I could open my browser and type localhost:8000. That was a local website that I could use to see how my website looks even when coding!

After that i could push my website to the fab cloud, This was done by pressing Source Control (Ctrl + Shift + G) on the sidebar, which for me looked a little something like this:

Source Control

Then I just pressed Commit and finally Sync. My code was now on the Fab Cloud!

Telling Gitlab how to host my website

To begin, I created a new file called .gitlab-ci.yml Inside the file i wrote this: 

pages:
  stage: deploy
  image: python:latest
  variables:
    GIT_DEPTH: 0
  script:
    - pip3 install mkdocs-git-revision-date-localized-plugin
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Next, i saved it I and pressed commit. and then checked my page which looked like this:

Correctly Setup up Page

Success! I now had a page that anyone can access and a place to document my journey!

Configuring and Personalizing my website

To begin, I opened the mkdocs.yml file and decided to use Svavar Konráðsson's configuration as a base, customizing it to fit my needs. One of the features I added was the ability to switch between light and dark modes using a light bulb icon next to the search bar. Here is the code for that:

theme:
  palette:
  - media: "(prefers-color-scheme: light)"  # Toggle for light mode
    scheme: default
    toggle: 
    icon: material/lightbulb
    name: Switch to dark mode
    primary: black
    accent: red
  - media: "(prefers-color-scheme: dark)"   # Toggle for dark mode
    scheme: slate
    toggle:
    icon: material/lightbulb-outline
    name: Switch to light mode
    primary: black 
    accent: red

Next, I changed the font to enhance the readability of the text and code:

# This code should go inside the theme section
  font:
  text: Roboto 
  code: Roboto Mono

I also added several useful Markdown extensions to improve the functionality of the site:

markdown_extensions:
  - pymdownx.snippets
  - pymdownx.keys
  - pymdownx.highlight:
    anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.superfences
  - pymdownx.tabbed:
    alternate_style: true
  - pymdownx.details
  - admonition
  - attr_list
  - md_in_html
  - pymdownx.arithmatex:
    generic: true
  - pymdownx.tasklist:
    custom_checkbox: true

After making these and a few other minor adjustments like changing the icons, I was extremely pleased with the final result!

Last Words

This week was very interesting. I learned about how to use Git and MKDocs Material which I am loving as a website maker. This week taught me a lot and I am very happy with my website.

Design Files

  • None

Software I used