Regression: Tabs are not shown properly

[janLo]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I've found a bug and checked that ...

• ... the problem doesn't occur with the mkdocs or readthedocs themes
• ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
• ... the documentation does not mention anything about my problem
• ... there are no open or closed issues that are related to my problem

Description

Tabs within the bage content suddenly does not render correctly anymore. Iget this in the javascript console:

Uncaught ReferenceError: Missing element: expected ".tabbed-labels" to be present

I made a minimal reporducer:
index.md:

# Welcome to MkDocs

=== "foo"
    bla
    blubb
    
=== "bar"
    peng pong

mkdocs.yml:

site_name: My Docs


theme:
  name: material
    
markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed

Output:

environment:

Python 3.9.9

requirements.txt:

mkdocs
git+https://pip:[email protected]/git/external/github.com/squidfunk/mkdocs-material-insiders.git#egg=mkdocs-material
pymdown-extensions

% pip freeze
cairocffi==1.3.0
CairoSVG==2.5.2
certifi==2021.10.8
cffi==1.15.0
charset-normalizer==2.0.9
click==8.0.3
cssselect2==0.4.1
defusedxml==0.7.1
ghp-import==2.0.2
idna==3.3
importlib-metadata==4.8.2
Jinja2==3.0.3
Markdown==3.3.6
MarkupSafe==2.0.1
mergedeep==1.3.4
mkdocs==1.2.3
mkdocs-material @ git+https://***/external/github.com/squidfunk/mkdocs-material-insiders.git@4b6b0232c27532f00eb9af50d6b8db5d9ce08592
mkdocs-material-extensions==1.0.3
packaging==21.3
Pillow==8.4.0
pycparser==2.21
Pygments==2.10.0
pymdown-extensions==9.1
pyparsing==3.0.6
python-dateutil==2.8.2
PyYAML==6.0
pyyaml_env_tag==0.1
requests==2.26.0
six==1.16.0
tinycss2==1.1.1
urllib3==1.26.7
watchdog==2.1.6
webencodings==0.5.1
zipp==3.6.0

Expected behaviour

The tabs should render correctly.

Actual behaviour

The tabs are not shown and an error occures in the js console.

When this happens other functionality (like the theme switch) is also affected and does not work anymore.

Steps to reproduce

1. Set up the env as mentioned above
2. run mkdocs serve

Package versions

• Python: 3.9.9
• MkDocs: 1.2.3
• Material: mkdocs-material-insiders.git@4b6b0232c27532f00eb9af50d6b8db5d9ce08592

Configuration

site_name: My Docs


theme:
  name: material

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed

System information

• Operating system: Linux (debian)
• Browser: Chrome/Chromium

[janLo]

According to git bisect this is the commit that introduced the problem:

0a6ade980f34345a999cecd5e8cc447f71924d32 is the first bad commit
commit 0a6ade980f34345a999cecd5e8cc447f71924d32
Author: squidfunk <[email protected]>
Date:   Sat Nov 13 14:15:20 2021 +0100

    Removed legacy Tabbed implementation

 material/assets/stylesheets/main.450eaa28.min.css  |   2 +
 .../assets/stylesheets/main.450eaa28.min.css.map   |   1 +
 material/assets/stylesheets/main.9bd947bf.min.css  |   2 -
 .../assets/stylesheets/main.9bd947bf.min.css.map   |   1 -
 material/base.html                                 |   2 +-
 .../main/extensions/pymdownx/_tabbed.scss          | 261 ++++++++-------------
 6 files changed, 96 insertions(+), 173 deletions(-)
 create mode 100644 material/assets/stylesheets/main.450eaa28.min.css
 create mode 100644 material/assets/stylesheets/main.450eaa28.min.css.map
 delete mode 100644 material/assets/stylesheets/main.9bd947bf.min.css
 delete mode 100644 material/assets/stylesheets/main.9bd947bf.min.css.map

[janLo]

Ok, digging deeper it seems that the missing alternate_style flag for pymdownx.tabbed is causing this. I've read' the background abouth the better implementation and understand the reasoning behind this change. I would just be very happy if such breaking changes could be announced somewhere prominently in the future. Be it a big warning if a dreprecated feature is in use, a blog post or just the changelog.

This would make it much easier to fix such things without bisecting and then reading the commit histrory :).

[squidfunk]

The breaking change was introduced in v8 which is a major release and it is prominently mentioned in the upgrade guide which contains step-by-step instructions. Any idea how we could improve this further? I’m happy to do so.

[janLo]

Oh I completely missed that - probably because I did not expect it in "Getting started".

I use the insiders version via git - as recommended here - this way I do not "intentionally" upgrade - I get the new version with every CI build. Therefore I would prefer if the build of the documentation would actually break instead of producing unintended output. I know that this is not always possible. In such a case I normally consult the release-page of the project first (https://github.com/squidfunk/mkdocs-material/releases) and seach dor breaking changes there. Maybe this is a giid Idea, to list them there. The details can still go in the actual documentation.

In my own projects I use semantic-release these days, as it automates this process for me to a certain extend (see https://github.com/semantic-release/semantic-release/releases/tag/v18.0.0 for an example). This parses the commit messages for known markers to create the changelog with the necessary information. I don't know if this would be an option, as the default/insiders split would probably need some extra work here.

[squidfunk]

I use the insiders version via git - as recommended here - this way I do not "intentionally" upgrade - I get the new version with every CI build.

Material for MkDocs and Insiders use semantic versioning, but not semantic release. I'm a huge fan and advocate of the former but not of the latter, because I don't like releases being triggered automatically.

In general, you shouldn't deploy straight away to production always trusting that everything works, especially when a major release happens. Insiders is versioned exactly like Material for MkDocs with git tags, so it's probably best to check out a specific version and always manually double-check when doing upgrades. Note that both, Material for MkDocs and Insiders received a major version bump on the latest version.

Therefore I would prefer if the build of the documentation would actually break instead of producing unintended output.

Me too. Unfortunately, this is not possible from a theme perspective. The "runtimes" that the theme has is template rendering, i.e. Jinja, which doesn't allow for throwing errors or aborting, and the JavaScript runtime, which is too late. Furthermore, there's currently no possibility for specifying a schema for theme configuration, which would be a much better approach. This is a limitation which you could raise over at MkDocs. It could also be implemented as part of a plugin, but it's so essential that it would better be baked into MkDocs without the need for the user to provide a plugin explicitly.