Mkdocs: Update mkdocs theme from Bootstrap 2 to 4

[adrwh]

Please include badges (and other) very useful styles used in Documentation projects.

• badges

[waylan]

The mkdocs theme uses Bootstrap 2 which does not include support for badges (you point to the Bootstrap 4 documentation). Note that we have not updated Bootstrap for the reason explained in #1107, namely a primary feature of our global navigation would be broken. To be fair, I have not investigated if version 4 resolves the issue.

[waylan]

A quick look at Bootstrap 4 indicates that like Bootstrap 3, only a single level of nesting is supported in menus. However, as we are documenting that the mkdocs theme only supports that many levels of nesting (see #1522), I suppose we don't have any reason to not update to a more recent Bootstrap version. The one possible issue with that is that some users may be using more than one level of nesting and have not noticed that mobile mode is broken. With the update, their nav would be broken in both modes.

In any event, I'm clarifying the scope of this issue to be about updating to Bootstrap 4.

[waylan]

As a reminder, the mkdocs theme is a custom Bootswatch theme (Bootswatch themes are built on top of bootstrap). The problem with doing this is that no one has the original source scss files used to build the custom Bootswatch theme. I'm not even sure which Bootswatch theme was used as the starting point, although I suspect the "default".

There are two ways to build a custom Bootswatch theme.

1. Start with the raw source files from the thomaspark/bootswatch repo. Edit _variables.scss (and possibly _bootswatch.scss) and then build the theme with a grunt command. See the docs for details.
2. Use Bootstrap's builder tool available through a web interface. This will let you import your bootswatch theme of choice to start, and then you can edit variables in a web form. When done, you can download a built set of theme files. IIRC, you can export your custom settings and save for later import.

What we need is for someone to go through the existing theme and figure out what all the variables were when it was first built. Then we can import them into a newer version to get an updated theme. And we also should save those variables for the next time we want to update.

[mitya57]

The problem with doing this is that no one has the original source scss files used to build the custom Bootswatch theme. I'm not even sure which Bootswatch theme was used as the starting point, although I suspect the "default".

It was the “cerulean” theme. Our CSS file is identical to that in v3.0.3+1 tag in Bootswatch Git repository:

https://github.com/thomaspark/bootswatch/tree/v3.0.3%2B1/cerulean

I suspect we can just update our copy to the latest upstream tag.

[waylan]

Thanks @mitya57 but its not that simple. I started the work in #1597 but I did the easy part. I don't have the time or inclination to bother with the rest, so if anyone wants the update, they need to do the work outlined there.