Mkdocs-material: Integrate Pymdown-Extensions Tabbed extension

[facelessuser]

__I checked that...__

• [x] ... the documentation does not mention anything about my idea
• [x] ... to my best knowledge, my idea wouldn't break something for other users
• [x] ... there are no open or closed issues that are related to my idea

Description

Need to do initial work for the new Tabbed extension that will release in pymdown-extensions 7.0. This adds general purpose tabs. Classes on previous SuperFences tabbed code change to match Tabbed.

Additional info on implementation is found in https://github.com/facelessuser/pymdown-extensions/issues/814.

Pull containing code is found: https://github.com/facelessuser/pymdown-extensions/issues/815

Use Cases

Allows the much requested any Markdown in tabs functionality.

Screenshots / Mockups

See related links.

[squidfunk]

@ofek already deployed it on https://datadoghq.dev/integrations-core/setup/#docker-linux, looks pretty good from the start. Adding the following line of CSS fixes the margin issue until we integrated it properly:

.superfences-content {
  margin: 0 .6rem .6rem
}

Note that this now also applies to code-only tabs.

[ofek]

Oh just saw this! FYI it's @ofek 🙂

[squidfunk]

Oops, mistyped your name - sorry!

[facelessuser]

One thing I'm realizing is that with a general purpose tab interface, it may be hard to serve up old style code tabs (where the code fills up the tab content area) and then have the general purpose padded tabs.

I guess you could pull it off if you could apply a specific class to a tab, but outside that, I'm not sure. I'll be interested to get feedback if we need to allow class injection into tabs, or if we just settle on a universal style and call that fine.

[squidfunk]

I think we should definitely let both co-exist for some time until we figure out how (i.e. if) we can consolidate functionality. It should be possible but I don't know all the cases we need to cater to.

[facelessuser]

We could allow the SuperFences style tabs to keep using the old style classes, and have Tabbed use different class names. Let me know if that is how you want to go. I can hold off on deprecating the old style if needed and just let them be two different things with similar structure except for the classes.

[facelessuser]

Yeah, I think we can get it to work without special classes: https://github.com/facelessuser/mkdocs-material/blob/tabbed/src/assets/stylesheets/extensions/pymdown/_tabbed.scss.

That seems to work pretty good. When a code block is alone, it fills the tab, when it isn't, all the content is padded.

[squidfunk]

If it works (haven't tested), a PR would be super-nice 🚀If you do, please use the refactor/rxjs-typescript branch - I'm very close to an RC.

[squidfunk]

@facelessuser as I'm not a Python guru, on a side note: is PyPI (ot pip respectively) able to handle pre-releases, i.e. can we publish the 5.0.0rc0? PEP-440 seems to indicate it's possible.

[ofek]

@squidfunk Yup! Though to install it you'd have to do --pre with --upgrade or explicitly pin.

[facelessuser]

@squidfunk, Yes you can do pre-releases. I just released a beta for pymdownx that I required for the Tabbed pull I just made for your repo.

I can help you get that configured for a pre-release if you need help.

[facelessuser]

You'll probably want to change this: https://github.com/squidfunk/mkdocs-material/blob/refactor/rxjs-typescript/setup.py#L52:

from "Development Status :: 5 - Production/Stable" to "Development Status :: 4 - Beta"

And probably this https://github.com/squidfunk/mkdocs-material/blob/refactor/rxjs-typescript/package.json#L3:

from 5.0.0-preview to 5.0.0rc1.

I believe that is how you populate your versions and dev status in setup.py.

I think that'll do it. When you release, PyPI should identify it as a pre-release: https://pypi.org/project/pymdown-extensions/#history. I'd just tag it in GitHub as a pre-release as well.

[ofek]

Just to clarify, only the version string is used to determine whether or not it's a beta. The Development Status is just metadata about a project's perceived stability in general.

[facelessuser]

Yes, it is meta data, and good form to match, but it you don't change it, you'll still be okay.

My projects automate that when the version is a prerelease version.

[squidfunk]

Great, so it'll be relatively save to push out the pre-release. There're also no issues with dependabot or other services like that? I don't really want to kick off a chain of automatic downstream PRs until we hit a stable state.

[facelessuser]

Dependabot shouldn't force a prerelease on anyone. I've done prereleases before and have never seen an issue. As far as I'm aware, people will have to explicitly require the prerelease to start using it.

[facelessuser]

Just an FYI, my plan is not to tag an official version 7 of pymdownx until after Material 5 is finalized and released. I imagine through all the Material RCs, the pymdownx 7 release will be a beta or RC. I'm doing this to avoid any issues with the old Material. Only Material 5 will automatically get my prerelease, and once 5 is freely available as an official release, I'll update pymdownx to an official release. At that point, if people have issues, I can instruct them to use Material 5 or lock their dependencies to an old version.

[squidfunk]

Sounds good to me.

[ofek]

Hmm, quick question: is there a branch of both where tabs still work? Newest facelessuser/pymdown-extensions.git@tabs they go away and become radios. I then tried (b/c it was mentioned) also upgrading to squidfunk/mkdocs-material.git@refactor/rxjs-typescript and get:

docs run-test: commands[0] | python -m mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:\Users\ofek\Desktop\code\integrations-core\site
Traceback (most recent call last):
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\runpy.py", line 193, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\__main__.py", line 199, in <module>
    cli()
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 717, in main
    rv = self.invoke(ctx)
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\click\core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\__main__.py", line 159, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\commands\build.py", line 288, in build
    _build_theme_template(template, env, files, config, nav)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\commands\build.py", line 114, in _build_theme_template
    output = _build_template(template_name, template, files, config, nav)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\mkdocs\commands\build.py", line 93, in _build_template
    output = template.render(context)
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\jinja2\environment.py", line 1090, in render
    self.environment.handle_exception()
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\jinja2\environment.py", line 832, in handle_exception
    reraise(*rewrite_traceback_stack(source=source))
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\jinja2\_compat.py", line 28, in reraise
    raise value.with_traceback(tb)
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\material\404.html", line 4, in top-level template code
    {% extends "base.html" %}
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\material\base.html", line 188, in top-level template code
    {% block footer %}
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\material\base.html", line 189, in block "footer"
    {% include "partials/footer.html" %}
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\material\partials\footer.html", line 59, in top-level template code
    {% include "partials/social.html" %}
  File "C:\Users\ofek\Desktop\code\integrations-core\.tox\docs\lib\site-packages\material\partials\social.html", line 8, in top-level template code
    {% include ".fontawesome/" ~ social.icon ~ ".svg" %}
  File "c:\users\ofek\appdata\local\programs\python\python38\lib\site-packages\jinja2\loaders.py", line 199, in get_source
    raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: .fontawesome/.svg

[squidfunk]

The refactoring branch is currently not considered stable. I'll expect to hit a stable state within the next few days and write up some guidelines how to migrate. The error in question originates from the fact that the social icon config changed:

- type: twitter
  link: https://twitter.com/squidfunk

becomes

- icon: brands/twitter
  link: https://twitter.com/squidfunk

[facelessuser]

The social link thing is the only real issue I think I ran into. That and having to hide the announcement bar, but I think that is fixed now.

I used to rely on some fontawesome font stuff for some custom things, but am looking to see if I can just include some of the SVG locally for those purposes. I realize things may break between now and the final, but I figure I can at least publish the beta docs using the new tab feature with explanation of how the feature works.

[facelessuser]

I should clarify, the social links wasn't an "issue", but a hiccup. As soon as I read the new docs I was fine.

[squidfunk]

I'll open a new issue for the beta where we'll document all the hiccups that are encountered during migration which will in the end make up the actual migration guide.

On that note, renaming type to icon was a deliberate decision as we're now actually including icons and it better matches the repo_icon which can also be a FontAwesome glyph.

[facelessuser]

Tabbed docs published with the latest experimental Material: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/.

Can't wait for the official RC.

[squidfunk]

There seems to be a dependency resolution problem again - somehow the current master seems to have picked up on the latest PymdownX beta version which is why tabs are now broken:

https://squidfunk.github.io/mkdocs-material/extensions/codehilite/#grouping-code-blocks

It was definitely deployed from master as it's happening for mkdocs-1.0.4, mkdocs-material-4.6.3 (from the meta tags). The requirements.txt lists:

https://github.com/squidfunk/mkdocs-material/blob/2980e4b39203cde40e6fb2b02365d52e6dec8f61/requirements.txt#L22-L25

[squidfunk]

... on a second note it may be related to Github Actions caching. I'll check that.

UPDATE: Very strange: the requirements.txt is hashed to resolve the cache and the docs are only deployed on the master branch:

https://github.com/squidfunk/mkdocs-material/blob/2980e4b39203cde40e6fb2b02365d52e6dec8f61/.github/workflows/ci.yml#L71-L75

and

https://github.com/squidfunk/mkdocs-material/blob/2980e4b39203cde40e6fb2b02365d52e6dec8f61/.github/workflows/ci.yml#L87-L96

Can't really explain what happened. I also tested a clean install in a virtual environment and 6.3 got picked up correctly.

[squidfunk]

It is a cache problem. I temporarily disabled caching and it started working again. I also removed the restore-keys as it seemed that pip fell back to a version without the hash, to no avail.

[facelessuser]

I haven't run into any issues, and I've been running workflows with the latest official Material. I never enable caching for pip in my workflows though. If disabling caching allows it to work, I'd do that.

[facelessuser]

If we need to, we could make things more backwards compatible. Instead of forcing SuperFences to use Tabbed classes, we just make it use the same classes it always did. We can leave the deprecated warning in regardless. All you'd need to do is just inherit the Tabbed rules for the legacy style classes. The general styling should work without change for the legacy style.

Technically, we are doing exactly what we should in regards to prereleases. Caching issues is quite separate from the approach we are using. But if we want to do both, the only thing I can think of is just duplicating the styles for the legacy classes.

[facelessuser]

With all it that said though, caching versions you don't intend to use can bite you in the future regardless of what we do in regards to pymdownx 7. It may have exposed an issue, but the issue is there still.

As is, even after the 7.0 release is official, old material versions can enable legacy_tab_classes in SuperFences to get things working like they used to, so it isn't completely incompatible. It's just the caching is forcing unexpected versions on you, and you are not prepared to mitigate the issue because you aren't expected a cached prerelease.

[facelessuser]

I guess you could also use tox to run your Python environments. That would create a virtual environment. And you can force tox to rebuild your Python virtual environment with the -r option.

I use tox.

[ofek]

Here's my working tox config if it helps:

[tox]
envlist =
    docs

[testenv]
passenv = *
basepython = python3
skip_install = true

[testenv:docs]
deps =
    ; pinning to get unreleased fix for Windows hotreloading https://github.com/mkdocs/mkdocs/issues/1885
    git+git://github.com/mkdocs/mkdocs.git@2fca717794c0c2e581b8ba17149bc292edeb83e4
    ; theme
    ; mkdocs-material>=5.0.0
    git+git://github.com/squidfunk/mkdocs-material.git@refactor/rxjs-typescript
    ; plugins
    mkdocs-minify-plugin>=0.2.3
    mkdocs-git-revision-date-localized-plugin>=0.4.6
    ; Extensions
    pymdown-extensions>=7.0b1
    mkautodoc>=0.1.0  # TODO: look into replacing with https://github.com/pawamoy/mkdocstrings
    ; Necessary for syntax highlighting in code blocks
    Pygments>=2.5.2
commands =
    python -m mkdocs {posargs}

[facelessuser]

yeah, if you are using tox, maybe you don't even have to use -r. I don't currently use it, but I also don't use the caching being used here:

https://github.com/facelessuser/pymdown-extensions/blob/master/tox.ini#L16

[facelessuser]

I guess I don't actually serve it with tox though: https://github.com/facelessuser/pymdown-extensions/blob/master/.github/workflows/deploy.yml#L10

[squidfunk]

Material for MkDocs 5.0.0rc1 is out which fixes this issue 😀 Let's test and improve it together!