Content tabs

[mhostetter]

Are content tabs supported in this theme? I searched in the docs here, but didn't find any mention. Thanks!

[2bndy5]

No. Not natively. To use content tabs in sphinx-immaterial, we recommend the sphinx-design extension. There are other extensions that get similar results, but we use sphinx-design in our docs.

[mhostetter]

Thanks for the response. I tried that extension and was able to get a set of tabs. However, the visual appearance isn't quite on par with the rest of sphinx-immaterial (the font is larger, different, etc).

I'm curious what technically it would take to produce Material for Mkdocs style content tabs. Could one add custom CSS so the tabs created by sphinx-design use the "styling" (whatever that is) from Material for Mkdocs? I'm not suggesting it should be done right now. Just trying to understand the technical challenges.

sphinx-design

Material for Mkdocs

[2bndy5]

The sphinx-design extension is very customizable from RST. But if you can't get what you want from using RST, then you can override the CSS (which tend to use classes that start with sd-). I had to do a little CSS tweaking in the sphinx-immaterial docs to get the colors to match (which is noted in the docs), but I didn't explore the font size difference.

You can find the SCSS (which gets compiled into CSS) from the mkdocs-material theme in src/assets/stylesheets/main/extensions/pymdownx/_tabbed.scss.

However, the easiest way to experiment with CSS changes might be using the browser web dev tools (just right click the tab's label and select "Inspect ..."). Then you can copy any changes you made from the browser dev console to your CSS file...

[2bndy5]

We can't support content tabs from the theme because the mkdocs-material theme uses a markdown extension to support content tabs. Since this markdown extension isn't used at all in the sphinx world (myRST parser doesn't even use it), we are forced to use a different solution (like the sphinx-design extension).

The drawback, as you've already noted, is that the CSS styling doesn't align well with the theme's CSS.

[jbms]

We could potentially add some type of sphinx-design integration so that the content tabs are styled consistently.

[2bndy5]

We could potentially add some type of sphinx-design integration so that the content tabs are styled consistently.

I've been avoiding this idea because it would pin us to using sphinx-design exclusively (there are other/simpler implementations out there). And, there's the matter of overriding CSS from the extension; I'm not sure where extensions' CSS are in the cascade relative to the theme's CSS.

ps - The furo theme did this and found it difficult to maintain when sphinx-design updates (the theme's overrides are currently slated for removal).

[mhostetter]

Is it easier/better to add a Sphinx directive in this theme, such as .. content-tabs:: (which could have similar syntax to sphinx-design), that would produce a tabbed window with the Material for Mkdocs theming?

[2bndy5]

Is it easier/better to add a Sphinx directive in this theme, such as .. content-tabs:: (which could have similar syntax to sphinx-design), that would produce a tabbed window with the Material for Mkdocs theming?

I'm more in favor of this approach since we had to do something like that to support admonitions without a title. We're also considering something like this for line number styles in literal code blocks

[2bndy5]

Just want to make note that synchronizing the common tabs on a certain page requires JS (which we may already have from upstream).

[jbms]

Providing our own implementation of content tabs seems reasonable assuming it is not too complicated.

I think in principle it might be possible to synchronize the tabs on a single page without JavaScript using fancy hidden form elements or something, but I think certainly synchronizing across multiple pages would require JavaScript in any case.

Unfortunately the cross-page synchronization of tabs is an "insider's only" feature in mkdocs-material so we would have to reimplement that if we want it:
https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs

[2bndy5]

I started looking closer at this. It looks like mkdocs-material implements the content tabs completely in TS where the HTML is just placeholders (with string-concatenated id attributes) for the TS, and the CSS seems strictly aesthetic. All user interaction seems to trigger a response from src/assets/javascripts/components/content/tabs/index.ts.

I'm still learning TypeScript, so reverse engineering a docutils based solution to interact with the TS may be more complex than I originally thought.

[jbms]

I am quite familiar with JavaScript but I am not familiar with rxjs, and I also find that the mkdocs-material javascript code can, unfortunately, be rather difficult to follow at times.

I would suggest ignoring the javascript and just looking at the HTML output from mkdocs/mkdocs-material for content tabs --- that is all that we need to replicate.

[2bndy5]

@mhostetter In the meantime, you can use the following to get sphinx-design tabs to look like mkdocs-material's content tabs:

/* *********************** sphinx-design tab-set style overrides ********************* */

.sd-tab-set>input:checked+label {
  border-color: var(--md-primary-fg-color);
  color: var(--md-primary-fg-color);
}

.sd-tab-set>input+label {
  font-size: 0.64rem;
}

.sd-tab-set>input:not(:checked)+label:hover {
  color: var(--md-primary-fg-color);
}

---

@jbms I only took a peek at the JS because the html seems heavily reliant on using id attributes.

<div class="tabbed-set tabbed-alternate" data-tabs="3:2" style="--md-indicator-x: 0px; --md-indicator-width: 113px;">
  <input checked="checked" id="__tabbed_3_1" name="__tabbed_3" type="radio">
  <input id="__tabbed_3_2" name="__tabbed_3" type="radio">
  <div class="tabbed-labels">
    <label for="__tabbed_3_1">Unordered list</label>
    <label for="__tabbed_3_2">Ordered list</label>
  </div>
  <div class="tabbed-content">
    <div class="tabbed-block">
      <ul>
        <li>Sed sagittis eleifend rutrum</li>
        <li>Donec vitae suscipit est</li>
        <li>Nulla tempor lobortis orci</li>
      </ul>
    </div>
    <div class="tabbed-block">
      <ol>
        <li>Sed sagittis eleifend rutrum</li>
        <li>Donec vitae suscipit est</li>
        <li>Nulla tempor lobortis orci</li>
      </ol>
    </div>
  </div>
</div>

Notice it keeps track of tabbed set and tab order number. __tabbed_3_1 is the first tab on the third set of tabs for that page. I think the data-tabs attribute sets the bounds for JS manipulation (doesn't seem to change depending on active tab).

[jbms]

I think this is the pymdown extension that produces the tab output:
https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/

It sounds like mkdocs-material uses the "alternate_style" output described at the bottom of the page.

[2bndy5]

Ah yes. I wasn't a big fan of how sphinx-design tabs wrapped into multiple lines for mobile's portrait viewport. That certainly helps. I'm imagining the new RST directives like so

.. md-tab-set::

   .. md-tab-item:: Label 1

      Some content.

   .. md-tab-item:: Label 2

      Some other content.

[mhostetter]

@2bndy5 thank you for the temporary workaround! This is helpful for learning how to find and override certain CSS rules. I appreciate it.

[2bndy5]

I have locally created/tested the necessary directives (md-tab-set & md-tab-item) to make use of the content tabs feature from upstream... stayed tuned. I'm currently looking into whatever else can/should be supported in this manner

[mhostetter]

Awesome @2bndy5! I'll test everything with my project when you're ready to share. Thanks for the help! 😄

[2bndy5]

@mhostetter Please update sphinx-immaterial to v0.4.0 to use the new directives

[mhostetter]

Great! Thank you, @2bndy5!

[mhostetter]

I am now using .. md-tab-set:: and .. md-tab-item:: in most places in my docs. There are a few places where I still rely on synced tabs, and so I'm still using sphinx-design for that.

Thanks to @2bndy5's initial set of CSS tweaks, I refined them to match Material for Mkdocs even more. So for anyone interested, here is the current set of CSS I'm adding to make .. tab-set:: and .. tab-item:: from sphinx-design match the content tabs from this theme.

(There may be some silly things here. I'm new to CSS and don't really know what I'm doing.)

.sd-tab-set>input+label {
  font: var(--md-text-font-family);
  font-size: 0.64rem;
  font-weight: bolder;
  border-bottom: .13rem solid transparent;
}
.sd-tab-set>input:checked+label {
  border-color: var(--md-accent-fg-color);
  color: var(--md-accent-fg-color);
}
.sd-tab-set>input:not(checked)+label {
  color: var(--md-default-fg-color--light);
}
.sd-tab-set>input:not(:checked)+label:hover {
  border-bottom: .0rem solid transparent;
  color: var(--md-accent-fg-color);
}
.sd-tab-content {
  box-shadow: 0 -0.05rem var(--md-default-fg-color--lightest);
}

Top is .. tab-set:: and bottom is .. md-tab-set::.