9.0 Migration Notes

Overview

There are many new features that come with 9.0, and a little housecleaning as well. This guide will touch on migration concerns related to removals, deprecations, and/or breaking changes.

In general, there should be no breaking changes in 9.0 unless you were still using old, already deprecated features.

Gone & Deprecated

Removed deprecated features:

Highlight's legacy_no_wrap_code option was removed. This used to allow people to output code blocks in Pygments' original way, which simply inserted code in a <pre> block. This was added all the way back in 6.3 and was only added to help transition people to the new output which is HTML5 compatible and wraps code in <pre><code> blocks. If you have styling or logic that depending on this old, deprecated option, you will have to update said styles and/or script logic to account for the new output.
Highlight's highlight_code option has formally been removed. This option as been a NOOP for a long time and was just left around in order to not break people's usage of Highlight. It has now been removed. If it was still hanging around in your config, it should simply be removed. Nothing functionally will change.
SuperFences, in 7.0, changed up the format of the custom fences. When custom fences were added, a full vision of how they would/should be used had not fully cemented, so unfortunately they have been revised occasionally, 7.0 being the most recent time. To help transition people, a fallback was left in with a warning. This fallback code has now been removed. Information regarding how to upgrade the format is available in the 7.0 release guide.

As far as deprecated functions and features are concerned:

Arithmatex has deprecated all of its SuperFences custom fence functions and instead has replaced it with two configurable methods. MkDocs users may have some concerns that these will not work in the YAML configuration, but fear not as things work just fine. Check out Arithmatex Custom Fences for more info.
PyMdown Extensions provided a number of slugify functions which, like with Arithmatex, have been consolidated into a single configurable function. With this consolidation, two new options have been added that allow applying Python's default case folding on slugs and allow configuring Unicode normalization. Personally, we feel NFC is the way to go, but if others disagree, this is now configurable. Check out One Slugify to Rule Them All. Much like the new Arithmatex formatters, these slugs, even though they are configurable, will work with MkDocs just fine.

Arithmatex

Arithmatex now as two new custom fences that can be used for InlineHilite and SuperFences: arithmatex_inline_format and arithmatex_fenced_format respectively. They can do everything the old methods can do and are configurable. The old formatters are still available, but have been deprecated.

arithmatex_inline_format is meant for InlineHilite and replaces all other inline formatters. The table below shows how to migrate:

Name	Migration
`inline_mathjax_preview_format`	`arithmatex_inline_format(mode="mathjax", preview=True)`
`inline_mathjax_format`	`arithmatex_inline_format(mode="mathjax")`
`inline_generic_format`	`arithmatex_inline_format(mode="generic")`

arithmatex_fenced_format is meant for SuperFences and replaces all related fenced style formatters.

Name	Migration
`fence_mathjax_preview_format`	`arithmatex_fenced_format(mode="mathjax", preview=True)`
`_inline_mathjax_format`	`arithmatex_fenced_format(mode="mathjax")`
`inline_generic_format`	`arithmatex_fenced_format(mode="generic")`

These new, custom fences also add some new features, like being able to change the wrapper element. If you happen to use MkDocs with Arithmatex, and happen to use mkdocs-minify-plugin, you may notice that some math blocks don't render proper. This is because the plugin butchers white space in the wrapper <div> element. Now you can wrap your math in a <pre> and move on . This is configurable as an Arithmatex option called block_tag and inline_tag. The custom fences and formatters also have a tag option where this can be configured.

MkDocs Users

Fear not, this works for MkDocs as well! Using the following syntax can allow you to specify the function with keyword arguments:

markdown_extensions:
  - pymdownx.superfences:
    custom_fences:
      - name: math
        class: arithmatex
        format: !!python/object/apply:pymdownx.arithmatex.arithmatex_fenced_format {kwds: {mode: generic, tag: pre}}

While the above is a personal preference as it keeps the arguments on the same line as the function, you can also specify them in this way which some may find cleaner:

markdown_extensions:
  - pymdownx.superfences:
    custom_fences:
      - name: math
        class: arithmatex
        format: !!python/object/apply:pymdownx.arithmatex.arithmatex_fenced_format
          kwds:
            mode: generic
            tag: pre

One Slugify to Rule Them All

Previously, the slug module provided numerous slugify functions, they have all been reduced to one configurable function. Migration is shown below:

Name	Migration
`uslugify`	`slugify(case="lower", percent_encode=True)`
`uslugify_encoded`	`slugify(case="lower", )`
`uslugify_cased`	`slugify(percent_encode=True)`
`uslugify_cased_encoded`	`slugify()`
`gfm`	`slugify(case="lower-ascii", percent_encode=True)`
`gfm_encoded`	`slugify(case="lower-ascii")`

Additionally, you can now set case="fold" to use Python's default case folding and set normalize to different Unicode normalization modes (NFC is default).

MkDocs Users

Fear not, this works for MkDocs as well! Using the following syntax can allow you to specify the function with keyword arguments:

markdown_extensions:
  - markdown.extensions.toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}

While the above is a personal preference as it keeps the arguments on the same line as the function, you can also specify them in this way which some may find cleaner:

markdown_extensions:
  - markdown.extensions.toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower