Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update mkdocs theme from Bootstrap 2 to 4 #1563

Closed
adrwh opened this issue Jul 22, 2018 · 5 comments
Closed

Update mkdocs theme from Bootstrap 2 to 4 #1563

adrwh opened this issue Jul 22, 2018 · 5 comments
Milestone

Comments

@adrwh
Copy link

@adrwh adrwh commented Jul 22, 2018

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

@waylan
Copy link
Member

@waylan waylan commented Jul 22, 2018

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
Copy link
Member

@waylan waylan commented Jul 22, 2018

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 waylan changed the title Include additional bootstrap classes Update mkdocs theme from Bootstrap 2 to 4 Jul 22, 2018
@waylan waylan added this to the Post 1.0 milestone Jul 22, 2018
@waylan
Copy link
Member

@waylan waylan commented Aug 16, 2018

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
Copy link
Contributor

@mitya57 mitya57 commented Aug 18, 2018

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
Copy link
Member

@waylan waylan commented Aug 20, 2018

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.

@waylan waylan removed this from the Post 1.0 milestone Aug 23, 2018
@waylan waylan added this to the 1.1 milestone Aug 23, 2018
@waylan waylan closed this in 54a6e9e Sep 27, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants