Using bootstrap with mkdocs-material

[gmatteo]

Since I'm not an experienced web-developer, I've decided to use mkdocs and mkdocs-material to generate the user documentation for our Fortran code.
Our website generated using mkdocs 0.17.5 and mkdocs-material 2.6.6 works nicely.

Now I'm trying to migrate to mkdocs 1.1.2 and mkdocs-material 7.0.6 to take advantage of new features and bug fixes.
Unfortunately, it seems that the bootstrap library I use to implement modal windows, buttons and popovers now comes into conflict with mkdocs-material.

This is what I get for the homepage if I load bootstrap 3.3.7:

These are the libraries loaded in main.html:

{% extends "base.html" %}

{% block libs %}
    {{ super() }}

    <!-- Jquery from Google CDN -->
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>

    <!-- Load Jquery UI -->
    <script src="https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"></script>
    <!-- Handle jQuery plugin naming conflict between jQuery UI and Bootstrap 
    https://stackoverflow.com/questions/13731400/jqueryui-tooltips-are-competing-with-twitter-bootstrap
    -->
    <script>
      $.widget.bridge('uibutton', $.ui.button);
      $.widget.bridge('uitooltip', $.ui.tooltip);
    </script>

    <link rel="stylesheet" href="https://code.jquery.com/ui/1.12.1/themes/base/jquery-ui.css">

    <!-- Bootstrap theme -->
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/alertifyjs@1.11.0/build/css/themes/bootstrap.min.css"/>

    <!-- Bootstrap http://getbootstrap.com/getting-started/ -->
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" 
    integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">

    <!-- Optional theme -->
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap-theme.min.css" 
    integrity="sha384-rHyoN1iRsVXV4nD0JutlnGaslCJuC7uwjduW9SVrLvRYooPp2bWYgmgJQIXwl/Sp" crossorigin="anonymous">
    -->

    <!-- Latest compiled and minified JavaScript -->
    <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" 
    integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous">
    </script>

Note that I get the correct layout if I remove:

    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" 
    integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">

but without this lib all the bootstrap components do not work properly.

I've inspected some of the HTML elements in the browser and I see that in some cases the CSS property
is taken from bootsrap.css but I cannot judge if this is the source of the problem
(I can provide further info if needed)

I would like to know if there's an easy solution to use bootstrap with the new version of mkdocs-material
or if you recommend replacing bootstrap with other solutions/libraries based on Material Design.

Best regards,
Matteo

[squidfunk]

Material for MkDocs is written from scratch, without the use of a CSS framework or library, except for SCSS and the Material Design color definitions. When you drop in Bootstrap, it might override some styles which might break the layout. Sadly, I don't have any experience using Bootstrap together with Material for MkDocs.

Note that 2.6.6 to 7.0.6 is a very big version jump. If you defined overrides, make sure to remove them from the beginning and add them gradually, to better isolate breaking things.

[gmatteo]

Thanks for the prompt reply.

At this point, I've decided to remove bootstrap and refactor my implementation using e.g. the button classes from mkdocs-material. Fortunately most of the HTML sections are generated from python markdown extensions I wrote so the changes will be very localized.

I still need to find a replacement from modal windows and I'm considering the Jbox plugin
based on jquery. I assume that this solution will be much less intrusive than bootstrap and, hopefully, it won't clashes with mkdocs-material.

Note that 2.6.6 to 7.0.6 is a very big version jump. If you defined overrides, make sure to remove them from the beginning and add them gradually, to better isolate breaking things.

Thanks for the tip. I managed to reintegrate the majority of my changes starting from the new templates available in v7.0.6.

[preston3271]

Hello @gmatteo and @squidfunk! I just posted a similar question about Mkdocs for Materials and Bootstrap 5 on Stackoverflow,
[How to combine mkdocs-materials and bootstrap 5 to work together](https://stackoverflow.com/questions/76478894/how-to-combine-mkdocs-materials-and-bootstrap-5-to-work-together) Please review this detailed post as it may bring light to my issue as well.

Now I did review the documentation on Customization documentation, but I struggled to fully grasp the understanding of the overrides at the time of my efforts. But @gmatteo example above helped. I think based upon the discussion here, for:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Bootstrap demo</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM" crossorigin="anonymous">
  </head>
  <body>
    <h1>Hello, world!</h1>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js" integrity="sha384-geWF76RCwLtnZ8qwWowPQNguL3RmwHVBC9FhGdlKrxdiJJigb/j/68SIy3Te4Bkz" crossorigin="anonymous"></script>
  </body>
</html>

Within the Mkdocs-Material overrides, within the main.html, it should be something like

{% extends "base.html" %}

{% block style%}
  
  {{ super() }}
 <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM" crossorigin="anonymous">

{% endblock %}


{% block scripts %}

  <!-- Add scripts that need to run before here -->
  {{ super() }}
  <!-- Add scripts that need to run afterwards here -->
   <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js" integrity="sha384-geWF76RCwLtnZ8qwWowPQNguL3RmwHVBC9FhGdlKrxdiJJigb/j/68SIy3Te4Bkz" crossorigin="anonymous"></script>

{% endblock %}

Am I heading in the right direction? Please advise. And, as of this post, I just saw w3shools "W3.CSS" framework, which is, as they say, a clean "A Quality Alternative to Bootstrap." Will this option work better with Mkdocs-Materials? Dang! Everyone is gunning for everyone else's projects.

[brio50]

@preston3271 - it's all about order of operations. loading bootstrap css and js first is crucial.

{% extends "base.html" %}

{% block styles %}
  <link rel="stylesheet" href="https://unpkg.com/bootstrap@5.3.3/dist/css/bootstrap.min.css">
{{ super() }}
{% endblock %}


<!-- https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#announcement-bar -->
<!-- When config.extra.announcement.enabled == false, there must be no space, otherwise the <aside></aside> 
      attribute from base.html will be rendered and a black bar will appear above the main navigation -->
{% block announce %}{% if config.extra.announcement.enabled %}<center>{{ config.extra.announcement.value }}</center>{% endif %}{% endblock %}

{% block scripts %}
  <script src="https://unpkg.com/bootstrap@5.3.3/dist/js/bootstrap.min.js"></script>
{{ super() }}
{% endblock %}

here's the corresponding extra.js to make Bootstrap > 5.3.0 color modes work with material theme

// https://squidfunk.github.io/mkdocs-material/customization/#additional-javascript

console.log("extra.js loaded");

const labelElements = document.querySelectorAll("label[for^='__palette_']");
labelElements.forEach(labelElement => {
  labelElement.addEventListener("click", () => {
    const htmlElement = document.querySelector("html");
    const currentTheme = htmlElement.getAttribute("data-bs-theme");
    const newTheme = (currentTheme === "dark") ? "light" : "dark";
    htmlElement.setAttribute("data-bs-theme", newTheme);
    console.log("data-bs-theme:", newTheme);
  });
});

// Set initial data-bs-theme attribute based on the opposite state
const htmlElement = document.querySelector("html");
const initialTheme = (htmlElement.getAttribute("data-bs-theme") === "dark") ? "light" : "dark";
htmlElement.setAttribute("data-bs-theme", initialTheme);
console.log("data-bs-theme:", initialTheme);

there's a bonus in my html snippet above that allows announcements to be specified in one's mkdocs.yml like so:

extra:
  announcement: 
    enabled: true
    value: > # accepts HTML
      <b>Annoucement</b>: Why 'ello!

[kdkiss]

I just created a mkdocs plugin, search GitHub for mkdocs-bootstrap-elements-plugin. Made it for personal use and still has some kinks to iron out but I had the same issue therefore made it. Check it out and if you have suggestions let me know.

[preston3271]

Thanks for the insight!

…

On Sun, Sep 1, 2024, 3:58 AM kdkiss ***@***.***> wrote: I just created a mkdocs plugin, search GitHub for mkdocs-bootstrap-elements-plugin. Made it for personal use and still has some kinks to iron out but I had the same issue therefore made it. Check it out and if you have suggestions let me know. — Reply to this email directly, view it on GitHub <#2461 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABFILM2H2VX6MFE6QO5RBZDZULQNXAVCNFSM6AAAAABNOIFPIOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTANJRGEZTINA> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[brio50]

I ultimately decided against using the Bootstrap framework. A file ‘_reset.scss’ in the package causes issues with material theme’s block spacing and font-size. I don’t want to be in the business of making css patches now and as versions of the material theme progress.

Bootstrap would be nice to have, its css rules are time savers. However I recommend against it for material theme at this current time.