Skip to content

1. Project management

This week I learned to setup my website and work on it locally using Git

Building a website

For this section I was given a website template on Gitlab that is written in markdown.

I signined into Gitlab.

I clicked on the only project i had (which is the website)

Here are all the files that pertain to the website.

Accessing Website URL

To find my websites url i went to Settings > Pages. This link is the url to my website.

Heres how my website looks like at the moment.

Website Customization

What is MKDocs?

MkDocs is a site generator that’s creates websites for documentation purposes. The website’s source files are written in Markdown but can be configured with YAML configuration file (mkdocs.yml).

It has several features including: -

  • Easy to customize
  • Great themes available
  • Preview your site as you work
  • Host anywhere

More information can be found on their offical website

Accessing Mkdocs.yml

To customize our website we need to edit the mkdocs.yml file. To find it go to your website repository and click mkdocs.yml.

The first section of the mkdocs file contains the site header and footer(top and bottom titles of a website) and under it are links to social media accounts.

Here’s what changed on the website.

Changing Colors

The Second section controls the colors of the website.


Scheme controls the background color of the website.

It can be set to Default for a white background.

Or to Slate for a black background.


If you dont see “scheme:” in your mkdocs file you can just add it under “palette:” and it will work.


Primary controls the colors of the top navigation bar.

Here are all the available colors you can choose from.

Lets say we had our primary color set to purple in the example below.

If we change the primary color to indigo the colors of buttons and the header change.


The Accent color controls the colors of all the interactable elements such as hovered links, buttons and scrollbars. Here are all the available colors you can choose from.

Notice that if we try to click the buttons on the side of the page it turns red. This is because the accent color is set to red.

Example Scenario

The currently my website looks like this.


  name: material
    scheme: slate
    # try other colors
    primary: teal
    accent: cyan

Website View

Lets change the background to white (setting scheme to default), the primary color to pink and the accent color to purple.


  name: material
    scheme: default
    # try other colors
    primary: pink
    accent: purple

Website View

You can find more examples of all the available options in the Mkdocs Color Documentation.

Changing Font

The third section controls the font of the website.

Changing the font is a simple process and can be done in 2 easy steps.

Step 1: Choose a font

Mkdocs supports all fonts from the Google Fonts website.

You can search for any font you like on the website.

As an example i will choose the Fredoka One font.


I suggest you research about the best fonts for websites, some fonts will make your documentation unclear.

I my favourite fonts are Lato, Poppins, Montserrat and Work Sans. I recommend that you try them out.

Step 2: Edit mkdocs

Typing the name of the font you chose after the text: value.


After saving the changes in mkdocs, you should have something like this.

You can find more examples of all the available font options in the MKdocs Font Documentation

Adding Extra features

The last section of the mkdocs controls extra features that can be added to the website.


Button Example

This is an example of what the button looks like.


You can add buttons by adding { .md-button } at the end of a link.

Here’s an example of the code.

[Assignments](./assignments/{ .md-button }
Adding Buttons

You can add buttons to your website by adding the code below to your mkdocs.yml file in the markdown_extensions section.

  - attr_list


Make sure that the button extention is not already installed in makdocs.

You can find more information in the Mkdocs Buttons Documentation


What are Admonitions

Admonitions are messages that can be put on a web page to give hints, warnings or other utilities.

Here are some examples of Admonitions.


Here is what a Admonition looks like on the page :)

Adding Admonitions

Add the code below to your mkdocs.yml file.

  - admonition
  - pymdownx.details
  - pymdownx.superfences
Using Admonitions

To use Admonitions in your website start with !!! followed by your type of message (Note,Tip,Warning,etc.). Press Enter on your keyboard to skip a line then press Tab to create a space then you can write your message.

!!! note

    Your message

This is what it looks like in the prieview

Extra Info

You can’t see Admonitions locally, they will only appear when when you visit your website.

You can find more information in the Mkdocs Admonitions Documentation

You can use the code below and replace your markdown_extensions section if you want too add all the extentions I have.

  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true 
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - attr_list
  - extra
  - smarty
  - codehilite:
      guess_lang: false
  - toc:
      permalink: true

Editing website locally using Git

Step 0: Setup & Prerequisites

  • Git installed
  • Editor of choice installed (This tutorial will use VS Code)
  • Working Gitlab website

Step 1: Cloning Website

Go to the website repository

Copy the Url under Clone with HTTPS

Step 2: Git Connection

Navigate to where you want to save your local website

Right Click > Git Bash here

Use the following code in the terminal

Git Clone *The URL you copied in step 1*

Enter your GitLab Username and Password

If everything worked fine you should have a folder that contains the same files that are on your repository

Step 3: Setup VS Code Enviroment

File > Open Folder > Folder you made in step 2

You should see all the files displayed in the to left of the screen

Step 4: Pushing Changes with Git

At this point you are free to edit the Website locally however you like

Once you are satisfied, save your work and proceed to the next step

Click the second icon on the toolbar (left side of the screen) to open the Source Control Menu

Click the check icon to commit changes

This prepares your files to be pushed (to be uploaded to GitLab)

A message box will appear on the top of the screen

Describe the changes you’ve made in the message box and Press Enter

Click … > Push

This will update your changes on GitLab

Step 5: Confirm Changes

You can makes sure that the changes have been pushed successfully by checking the Commits section in GitLab

You can also see what exactly has changed by clicking one of the commit messages.

Last update: February 26, 2022