mkdocs hacking

This page is a list of some hacks I did to hack mkdocs (version 1.6.1) and the bootstrap.386 theme (version 0.0.2), in no particular order.

Preventing text overlap

There seems to be a bug with Bootstrap.386 theme (at least in the version 0.0.2) where text from the navigation menu on the left can overlap on the content text, at least on a 720p display from a desktop browser (mobile version seems fine). To fix this one must add the following css code :

.affix { position:relative !important; }

This remove the "fixed" attribute from the class "affix" which the navigation menu inherit from.

To make this code applied to the site, one should add it to a "style.css" file in a "css" folder created within the "docs" folder, then add the following lines to the "mkdocs.yml" file :

extra_css:
    - css/style.css

Removing all javascript

Removing all javascript lower the bloat on the website but prevents some amenities like the search function (which I don't use) and the cursor animation which scrolls vertically when a page is loading (which I find distracting).

Removing javascript can be done by altering the template of the theme.

One should follow this instructions to do so :

Add the following line in the "mkdocs.yml" file, in the "theme" section :
```
custom_dir: overrides
```

Create a "main.html" file in an "overrides" folder which sits at the same level as the "mkdocs.yml" file. Put the following code in it :

{% extends "base.html" %}

{% block libs %}
<!-- Header javascript removed -->
{% endblock %}

{% block scripts %}
<!-- Footer javascript removed -->
{% endblock %}

Preventing the first letter of the site's title to disappear when hovering

In the extra "style.css" one added before (see this document "Prevent text overlap" section), add the following lines :

.navbar-header > a:hover::first-letter,
.navbar-header > a:focus::first-letter {
    color: #000000 !important;
}

Changing colors of the theme

In the extra "style.css" one added before (see this document "Prevent text overlap" section), add the following lines :

.affix {
    background-color: #bbbbbb !important;
}

a {
    background-color: #ffff00;
    color: #000000;
}


.navbar-header > a:hover,
.navbar-header > a:focus {
    background-color: #ee0000 !important;
}
.navbar-header > a:hover::first-letter,
.navbar-header > a:focus::first-letter {
    color: #000000 !important;
}

.nav > li > a {
    color: #000000 !important;
    background-color: #bbbbbb !important;
}

.bs-sidenav > li > a:before {
    content: '■ ';
}

.nav > li > a:hover {
    color: #ffffff !important;
    background-color: #000000 !important;
}
.nav > li > a:hover {
    color: #ffffff !important;
    background-color: #000000 !important;
}

h1,h2,h3,h4,h5,h6 {
    color: #ffffff !important;
    background-color: #0000ff !important;
}

body {
    background-color: #000000 !important;
}

strong {
    background-color: #ff0000 !important;
    color: #ffffff !important;
    padding-left: 0.25em;
    padding-right: 0.25em;
}

Highlighting links

In the extra "style.css" file created before (see this document "Prevent text overlap" section), add the following lines :

a {
    background-color: #0000ff !important;
    color: #ffff00 !important;
}

Highlighting titles

In the extra "style.css" file created before (see this document "Prevent text overlap" section), add the following lines :

h1,h2,h3,h4,h5,h6 {
    background-color: #0000ff !important;
}

h1:before,
h2:before,
h3:before,
h4:before,
h5:before,
h6:before
{
    content: '■ ';
}

Changing the favicon

Find some type of aesthetic you like ; this wiki documents the history of aesthetics so you should check it out and find something you like. I have a softness for Wacky Pomo as it reminds me of computer games from the late 80's/early 90's.
Search for words describing exactly your aesthetic/artistic movement, or for word related to it on every one's favorite search engine : Discmaster. Be sure to filter by images and to put "ico" (without quotes) in the "extension" field.
Download the icon and put it in a "img" folder under "docs" and then add the following line in "mkdocs.yml" under the section "theme"
```
favicon: img/favicon.png
```
Don't forget to clear your browser cache and refresh the page if your icon isn't displaying after you rebuilt/serve your website with mkdocs

TODO Somehow the mobile button looks both buggy and isn't displaying the menu in the mobile version of bootstrap386.

Forcing text wrapping on section titles

The mobile CSS of bootstrap386 theme as some issues like long section titles that are cut. This is because the text isn't wrapping. To fix that, in the extra "style.css" file created before (see this document "Prevent text overlap" section), add the following lines :

h2 {
    white-space: wrap !important;
}