V. customizing MkDocs¶

configuring MkDocs¶

In My Environment Setup I’ve shown you, how to setup and start MkDocs on the local computer.

For customizing our website, there is a mkdocs.yaml in the root of our repository directory. It’s more or less self-explained, so it’s very easy, to give the page a personal touch.
A complete tutorial is available at the MkDocs homepage , so I’ll show here just, how I customized my site.
I found another good tutorial at https://alinex.gitlab.io/env/mkdocs/

Okay…looking inside the mkdocs.yaml we see something like a “Header”

extra_css:
  - stylesheets/extra.css

# Replace the text below to customize your site
site_name: Lars Mattern - Fab Academy 2021
site_description: Fab Academy documentation site for Lars Mattern
site_author: Lars Mattern
copyright: Copyright 2021 Lars Mattern - Creative Commons Attribution Non-Commercial

site_url: http://fabacademy.org/2021/labs/bottrop/students/lars-mattern

I’ve added a stylesheet on top of the file. That gives me the possibility to add and define more colors.
More about that, later.
As I said, the rest is self-explained.

In the “extra - social” part, we can add some social media stuff.

extra:
  social:
    # For other social icons at https://squidfunk.github.io/mkdocs-material/setup/adding-social-links/
    - icon: fontawesome/brands/instagram
      link: https://instagram.com/fabacademany
    - icon: fontawesome/brands/facebook
      link: https://facebook.com/fabacademany
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/fabacademany
    - icon: fontawesome/brands/linkedin
      link: "https://linkedin.com/in/academany"

I don’t have any social media, so I leave it as is.

theme¶

We are using the material-theme here. Themes needs to be installed, before we can use it. I’ve described it also in My Environment Setup

theme:
  name: material

But it’s pretty funny to play around and try other themes. When we install and change the theme e.g. to bootstrap386 :

Install locally with pip install mkdocs-bootstrap386
And change theme in mkdocs.yaml

theme:
  name: bootstrap386

It looks like this …

If we would like to use this online, then we have to edit the requirements.txt which is also in the root directory of our repository.

In this file, we have to change the theme. In the following example, I put a comment mark before the material theme and added mkdocs-bootstrap386

# Add your custom theme if not inside a theme_dir
# (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
# mkdocs-material ~= 6.2
mkdocs-bootstrap386

If we forget to change the theme in the requirements.txt, then gitlab will run into an error :

But sadly, bootstrap386 messed up the side menu bar…

So, I switched back to material.

palette¶

In this part, I changed the primary color to brown and the accent color to deep orange.
The color palette is listed here

  palette:
    # try other colors https://squidfunk.github.io/mkdocs-material/getting-started/#primary-colors
    primary: brown
    accent: deep orange

primary <- sets the color of the top bar and the color of clickable links.
accent <- sets the color of highlighting.

fonts¶

You can spend HOURS to find a font for your page. MkDocs uses google fonts

  font:
    # See available fonts at https://fonts.google.com/
    text: Bangers
    code: Ubuntu Mono

text <- is the main font. Changing it e.g., to Press Start 2P would look like this :

I like the retro-style, but it’s harder to read, then my preferred Bangers font :-D

code <- changes the font of the code sections.

icons¶

Just a quick look inside the icons part

  icon:
    logo: material/rocket-launch-outline
  favicon: images/favicon.svg

logo <- changes the icon in the title bar top left. There are thousands available inside the material-theme library
I changed the default icon to rocket-launch-outline

favicon <- changes the tab and favorite icon from the browser. You can use the predefined icons from the list above or you can use an own vector graphics

stylesheet¶

In the mkdocs.yaml there is no way, to change the background color directly. That’s the reason, why I added a ‘stylesheet’ called extra.css which is shown in the HEAD section on top.

extra_css:
  - stylesheets/extra.css

With the following content, I changed the background color

:root {
  --md-default-bg-color:        #DDC470;
}

More information about customizing is available here
I used the color picker from w3schools to choose my preferred background color

I left the rest of the config file as it was.

The pre-installed navigation template was nice, but I changed it completely.
I think, I found a good way now, to organize my website.

It’s hard to explain, but I’ll do my best :-D

MkDocs inserts automatically a navigation bar and generates a side-navigation menu.
It’s a combination between the file-folder structure and the headline of each .md file (not the filename!)

My folder structure now looks like this…

Let’s have a look on the folders: about, assignments and downloads
When there is a .md file inside one of the folders, MkDocs generates an entry in the top navigation bar, which is named like the folder.

The file-folder ‘downloads’ doesn’t have .md files inside. That’s the reason, why there is no ‘download’ entry in the top navigation bar.

So far…so good…

In the file-folder assignments , I’ve added a sub-folder called 1. Project management In the 1. Project management folder are some .md files. (see screenshot above)
Now let’s compare the side navigation menu, with the folder structure above.

You see here ‘assignments’ with a sub-menu ‘1. Project management’
And the sub-menu ‘1. Project management’ has sub-entries.
The sub-entries are named by the ‘Headline’ which is inside each .md file.

Example:

The file 1_week01.md has the following content (Title) on top :

# I. Overview

Here is a sheet for a better understanding

File-Name	Headline = Sub-Entry
`1_week01.md`	`# I. Overview`
`2_setup.md`	`# II. My Environment Setup`
`3_git.md`	`# III. using git`
`4_html.md`	`# IV. little html walk through`
`5_mkdocs.md`	`# V. using Markdown & MkDocs`

The sorting of the sub-entries depends on the sorting of the file names.
That’s the reason, why I numerated the .md files.

table of content¶

On the right side, there is a ‘Table of content’

It will be filled with content by adding titles (headlines) and subtitles inside the .md files.
More about adding headlines are in my markdown section

And that’s the secret behind the automatic generated menu structure. :-)

add a second font¶

Over the weeks I have noticed that the font I have chosen is difficult to read, so I decided to change that. I’ve kept my main font for headers and the menu and changed the main text to another one.

The mkdocs.yaml has to be edited, that the second font will be loaded

extra_css:
  - stylesheets/extra.css
  - https://fonts.googleapis.com/css2?family=Bangers&display=swap

and I changed the main font:

  font:
    text: Monteserrat

In the extra.css I’ve added

.md-header,
.md-footer,
.md-typeset h1,
.md-typeset h2,
.md-typeset h3,
.md-tabs,
.md-header-nav__topic,
.md-sidebar {
  font-family: 'Bangers', cursive;
}

V. customizing MkDocs¶

configuring MkDocs¶

header¶

theme¶

palette¶

fonts¶

icons¶

stylesheet¶

insert doks and navigation¶

navigation bar¶

side navigation menu¶

table of content¶

add a second font¶

V. customizing MkDocs¶

configuring MkDocs¶

header¶

social media¶

theme¶

palette¶

fonts¶

icons¶

stylesheet¶

insert doks and navigation¶

navigation bar¶

side navigation menu¶

table of content¶

add a second font¶