explicitly exempt a content tab (or entire set of tabs) from being synced

[2bndy5]

We were thinking of implementing linked content tabs downstream in sphinx-immaterial, but then the feature was transitioned from insiders to "public" releases. One of the ideas we had was explicitly controlling the linked-tabs feature on a tab-set or individual tab basis.

So, I'm asking if this is an idea that would be viable here. I'm not sure if attrs can be specified by the user; my first idea looks like using the attr_list MD extension but appended to the tab declaration:

=== "C" { .no-tab-sync }

    ``` c
    #include <stdio.h>

    int main(void) {
      printf("Hello world!\n");
      return 0;
    }
    ```

=== "C++" { .no-tab-sync }

    ``` c++
    #include <iostream>

    int main(void) {
      std::cout << "Hello world!" << std::endl;
      return 0;
    }
    ```

IDK how else a user would assign an attribute or CSS class to a tab or entire set of tabs in mkdocs-material or pymdownx (its very easy with sphinx-immaterial).

Note

I used the term "sync" in the above example to not confuse with the insiders' feature about slugified tab labels that render as hyperlink-able tab labels.

[squidfunk]

Attribute Lists cannot be used on tabs. Please see #4268 + all that is related.

[facelessuser]

but I'm not sure if that would be sustainable (which I think constitutes a plugin), but I'm not sure if that would be sustainable (given the experimental nature of the new/proposed syntax) or if it would even be specific to this theme (referring to the JS machinery around linked tabs).

I don't understand why this wouldn't be sustainable. It is happening as it solves a number of problems. I've already implemented tabs within them and they work fine in Material. Nothing in Pymdown Extensions is specific to Material, but we've definitely made changes that help Material.

Will it be possible to generate the same old tabs with the new syntax? Yes. Will you be able to add arbitrary classes? Yes. But generating arbitrary classes is only half of what you need, Material would need to recognize those classes and actually do something (or not do something in this case).

Personally, I don't see why you'd want to add a class to every tab. If you wanted to avoid tab syncing in a tab group, you don't want to only avoid syncing on a specific tab, but the whole block. Why not do something like this?

<div class="no-tab-sync" markdown>

=== "C"

    ``` c
    #include <stdio.h>

    int main(void) {
      printf("Hello world!\n");
      return 0;
    }
    ```

=== "C++"

    ``` c++
    #include <iostream>

    int main(void) {
      std::cout << "Hello world!" << std::endl;
      return 0;
    }
    ```

</div>

Material would still need to recognize this and do something, but this would probably lend itself better to what you want I would think.

[2bndy5]

Personally, I don't see why you'd want to add a class to every tab.

It was just an example, and I didn't know how to apply the class to the whole set. In practice, I think it would only be useful for a tab set, but why stop there? There are some instances where our docs' examples use a common tab named "CSS hint", and the tab sets used in the examples aren't all related to each other. While other labels in the examples don't exactly match, It would be preferrable to exempt the linking of tabs that do have common labels.

I'm coming from sphinx, so I'm used to the extending the rST flexibility to the end user. That's why when I wrote the rST side downstream (which makes use of the material JS we inherit from here), I added the typical :class: and :name: options to the directives (demo'd in our docs).

Why not do something like this?

I'm not a fan of using raw HTML in doc sources. My MD linter actually discourages that habit by default. I just don't like the idea of forcing the user to learn/understand 2 different syntax, but maybe that "last resort" is common in writing MD.

But generating arbitrary classes is only half of what you need,

Exactly why I'm discussing it here. If the JS is not Material theme specific (and more pymdownx specific), then please forgive my mistake. I seem to have a history of rejected proposals here that are still applicable downstream, most of which are centered around edge case customization. One of these days I'll find a way to give back to this great theme.

[facelessuser]

I'm not a fan of using raw HTML in doc sources. My MD linter actually discourages that habit by default. I just don't like the idea of forcing the user to learn/understand 2 different syntax, but maybe that "last resort" is common in writing MD.

The new generic block syntax will allow arbitrary HTML block creation without requiring raw HTML.

Exactly why I'm discussing it here. If the JS is not Material theme specific (and more pymdownx specific), then please forgive my mistake. I seem to have a history of rejected proposals here that are still applicable downstream, most of which are centered around edge case customization. One of these days I'll find a way to give back to this great theme.

Markdown syntax is often dictated by upstream Python Markdown extensions. Some general documentation features are often dictated by upstream MkDocs plugins, though, the Material theme seems to have dabbled a bit more in this area. Often front-end things are provided by Material, and I feel a few general documentation site plugins have also been implemented in the theme. When it comes to Markdown syntax, that usually relies on Markdown extensions.

The original Tabbed and Details plugins were all based on the original Admonition plugin that ships with Python Markdown, and as such, they share a couple of the same limitations. The new general-purpose blocks aim to solve a number of issues.

• Currently, for every new block type syntax, you have come up with some new header. Over time, you start to run out of unique headers and things turn into syntax soup.
• The original Admonitions block used this indented format. Now we have multiple blocks that use indented format, and most people's editors just confuse this as indented code blocks which isn't ideal.
• The way that Admontions was originally written, the syntax was so lax in the header, that adding attribute support would break backward compatibility. There are ways around this, but it doesn't solve the aforementioned issues above.

The new generic blocks are close to being testable by a larger audience. Whether the syntax or API goes through some revisions before the official release, I will be pushing forward with them regardless. They will most likely come with support for creating arbitrary HTML blocks, Admonitions, Details, Tabs, and maybe even Definitions out of the box. There is a possibility we will add Figures and other support in the future as well.

While I do not intend to immediately get rid of the legacy extensions (Tabbed and Details). The intent is to fully replace them at some time in the future. If people really, really can't let go of these legacy extensions, we may offer them in some legacy repo at some future time (think at least a couple of years) when we finally discontinue them.

[2bndy5]

The new generic block syntax will allow arbitrary HTML block creation without requiring raw HTML.

Yes, I'm totally sold on that new syntax. In fact, I think it would make migrating from mkdocs to sphinx + MyST less nuanced. Can't wait for it to go mainstream! This thread is now more concerned with the JS side though.

The original Tabbed and Details plugins were all based on the original Admonition plugin

That explains why the details/summary tags are exclusively tied to admonitions in material's CSS. We've encountered problems downstream with various sphinx extensions that implement the details/summary elements., Ultimately, we had to monkeypatch sphinxcontrib-details-directive extension to properly support CSS classes, thus utilizing the CSS inherited from here.

we may offer them in some legacy repo at some future time (think at least a couple of years) when we finally discontinue them.

Given the maturity of mkdocs, I would think 2 years is an aggressive minimum. But I'm so enthusiastic about the newer syntax, that I would start using it tomorrow without hesitation. It would be even better if there was an escape hatch to the legacy repo when the newer syntax parser encounters legacy syntax, but I imagine that would be next to impossible to implement.

[facelessuser]

Given the maturity of mkdocs, I would think 2 years is an aggressive minimum.

Well, I'm throwing out 2 years as a minimum. I don't know what it is actually going to be, but regardless, they won't disappear for a while, and I may end up moving them to a place where they can live forever, albeit I probably won't update them anymore once we move away from them.