Comments (21)
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
from sphinx-immaterial.
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.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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
from sphinx-immaterial.
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::
.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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
from sphinx-immaterial.
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...
from sphinx-immaterial.
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.
from sphinx-immaterial.
We could potentially add some type of sphinx-design integration so that the content tabs are styled consistently.
from sphinx-immaterial.
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).
from sphinx-immaterial.
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?
from sphinx-immaterial.
Is it easier/better to add a Sphinx directive in this theme, such as
.. content-tabs::
(which could have similar syntax tosphinx-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
from sphinx-immaterial.
Just want to make note that synchronizing the common tabs on a certain page requires JS (which we may already have from upstream).
from sphinx-immaterial.
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.
from sphinx-immaterial.
@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).
from sphinx-immaterial.
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.
from sphinx-immaterial.
@2bndy5 thank you for the temporary workaround! This is helpful for learning how to find and override certain CSS rules. I appreciate it.
from sphinx-immaterial.
Awesome @2bndy5! I'll test everything with my project when you're ready to share. Thanks for the help! 😄
from sphinx-immaterial.
@mhostetter Please update sphinx-immaterial to v0.4.0 to use the new directives
from sphinx-immaterial.
Great! Thank you, @2bndy5!
from sphinx-immaterial.
Related Issues (20)
- pydantic 2.5.0 release just broke this package HOT 6
- "Edit this page" on RTD HOT 9
- use libgit2 directly in merge script HOT 2
- Extra whitespace for rendered footnotes/citations HOT 10
- Rendering of :kbd: role is a bit off HOT 7
- document the `theme_result` extension
- Feature request: Mermaid js 10.x
- genindex / modindex seems broken HOT 1
- [jupiter-book] Missing Table of Contents HOT 1
- Google Fonts API key invalid? HOT 16
- "Copy to clipboard" and "Back to top" Buttons Disappear After Adjusting Theme Settings HOT 7
- Broken link to fontawesome/brands icons HOT 1
- implement blog plugin from upstream
- add role for custom hyperlinks HOT 1
- add extension for supplementing git stats about doc sources HOT 1
- add directive(s) to support grids
- sphinx~=7.3.0 breaks sphinx-immaterial HOT 11
- Language switch to currently opened page HOT 5
- Anchoring a content tab possible? HOT 5
- sphinx_immaterial.google_fonts._MAX_CONCURRENT_FETCHES variable is unused HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from sphinx-immaterial.