Mkdocs-material: Preventive measures for changes coming in Python Markdown

[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

This is an informative request that I think mkdocs-material should be aware of.

1. Python Markdown (most likley in 3.2) is planning to have code blocks use Pygment's feature to ensure code blocks are wrapped in <pre> elements. Previously they where in the form <div class="codehilite"><code></code></div>, but moving forward, they will be in the form <div class="codehilite"><pre><code></code></pre></div>.

   To be honest, this change makes sense to me as this is what most people expect with code blocks, but Python Markdown will not provide a way to render the old way.

   reference: https://github.com/Python-Markdown/markdown/pull/862

2. pymdown-extensions will also follow suite, but will provide a temporary switch to get legacy behavior for a time. This is targeted for 6.2: https://github.com/facelessuser/pymdown-extensions/pull/698.

I think it may be wise in the next release(s) to lock requirements require Python Markdown <3.2 and pymdown-extensions <6.2. This would be done until 3.2 and 6.2 are released, then you could update styling to account for this and move forward requiring >=3.2 and >=6.2.

In my tests, all that was required in style is this:

  div.codehilite > pre {
    padding: 0;
  }

This is an override in pymdown-extensions styles and seems to be sufficient in accounting for the changes once they are in place.

Use Cases

I feel this suggestion will help to prevent unexpected styling due to future dependency releases.

Screenshots / Mockups

NA

[squidfunk]

Thanks for the upfront notice, the thorough description and potential solution! I was wondering why Pygments did implement it this way anyway. There're probably some rules/selectors that can be eliminated in Material's CSS which are currently necessary due to the inconsistent markup.

Feel free to submit a PR which locks the versions as described. Also, when both upstream repositories changed, feel free to submit another PR to upgrade to the new behavior. I will issue a new release straight away.

The CSS refactoring is on my part and will happen in the scope of Material v5.

[facelessuser]

I may push the pymdown change out to 6.3 and roll out the Twemoji changes in 6.2. But I'll take on this task and issue a pull request.

[AbhaysinghBhosale]

mkdocs is using markdown extension which is released with version 3.2.

Now after there release mkdocs build failing due to mkdocs-material 4.6.0 expecting markdown < 3,2.

Can anyone please let me know how i can update the markdown version in theme or mkdocs.yml to restring to <3.2 ie 3.1.1

[madmpro]

kdocs is using markdown extension which is released with version 3.2.

Confirmed. Please give a solution!

[squidfunk]

I just checked the dependeny tree of Material for MkDocs:

mkdocs-minify-plugin==0.2.1
  - htmlmin [required: >=0.1.4, installed: 0.1.12]
  - jsmin [required: >=2.2.2, installed: 2.2.2]
  - mkdocs [required: >=1.0.4, installed: 1.0.4]
    - click [required: >=3.3, installed: 7.0]
    - Jinja2 [required: >=2.7.1, installed: 2.10.3]
      - MarkupSafe [required: >=0.23, installed: 1.1.1]
    - livereload [required: >=2.5.1, installed: 2.6.1]
      - six [required: Any, installed: 1.13.0]
      - tornado [required: Any, installed: 6.0.3]
    - Markdown [required: >=2.3.1, installed: 3.1.1]
      - setuptools [required: >=36, installed: 42.0.2]
    - PyYAML [required: >=3.10, installed: 5.2]
    - tornado [required: >=5.0, installed: 6.0.3]
Pygments==2.5.2
pymdown-extensions==6.2
  - Markdown [required: >=3.0.1, installed: 3.1.1]
    - setuptools [required: >=36, installed: 42.0.2]
  - pep562 [required: Any, installed: 1.0]

The latest MkDocs version is v1.0.4 which demands Markdown v2.3.1. MkDocs v1.1 will up this to v3.0.1 (see here) which should satisfy <v3.2 (see here).

[madmpro]

Please give a solution!

I added requirement
markdown>=3.1,<3.2
to my project. That solved my compatibility problem.

https://github.com/squidfunk/mkdocs-material/issues/1450#issuecomment-583283375

[squidfunk]

@madmpro what's important is to understand where this incompatibility issue came from. Are you using any other Markdown extensions besides Material and Pymdown?

[Angelmmiguel]

I'm getting this error since today:

ERROR: mkdocs-material 4.6.0 has requirement markdown<3.2, but you'll have markdown 3.2 which is incompatible.

I'm using python 3.7.4 and just install mkdocs and mkdocs-material as dependencies:

# Install dpendencies
pip install --upgrade pip
pip install mkdocs mkdocs-material

This is the full output:

Collecting pip
  Downloading https://files.pythonhosted.org/packages/54/0c/d01aa759fdc501a58f431eb594a17495f15b88da142ce14b5845662c13f3/pip-20.0.2-py2.py3-none-any.whl (1.4MB)
    100% |████████████████████████████████| 1.4MB 583kB/s
Installing collected packages: pip
  Found existing installation: pip 8.1.1
    Uninstalling pip-8.1.1:
      Successfully uninstalled pip-8.1.1
Successfully installed pip-19.0.3
Collecting mkdocs
  Downloading mkdocs-1.0.4-py2.py3-none-any.whl (1.2 MB)
     |████████████████████████████████| 1.2 MB 568 kB/s
Collecting mkdocs-material
  Downloading mkdocs_material-4.6.0-py2.py3-none-any.whl (722 kB)
     |████████████████████████████████| 722 kB 8.0 MB/s
Collecting Markdown>=2.3.1
  Downloading Markdown-3.2-py2.py3-none-any.whl (88 kB)
     |████████████████████████████████| 88 kB 8.4 MB/s
Collecting Jinja2>=2.7.1
  Downloading Jinja2-2.11.1-py2.py3-none-any.whl (126 kB)
     |████████████████████████████████| 126 kB 11.3 MB/s
Collecting click>=3.3
  Downloading Click-7.0-py2.py3-none-any.whl (81 kB)
     |████████████████████████████████| 81 kB 8.1 MB/s
Collecting tornado>=5.0
  Downloading tornado-6.0.3.tar.gz (482 kB)
     |████████████████████████████████| 482 kB 2.5 MB/s
Collecting livereload>=2.5.1
  Downloading livereload-2.6.1-py2.py3-none-any.whl (23 kB)
Collecting PyYAML>=3.10
  Downloading PyYAML-5.3.tar.gz (268 kB)
     |████████████████████████████████| 268 kB 8.5 MB/s
Collecting Pygments>=2.2
  Downloading Pygments-2.5.2-py2.py3-none-any.whl (896 kB)
     |████████████████████████████████| 896 kB 11.5 MB/s
Collecting pymdown-extensions<6.3,>=6.2
  Downloading pymdown_extensions-6.2.1-py2.py3-none-any.whl (198 kB)
     |████████████████████████████████| 198 kB 12.1 MB/s
Collecting mkdocs-minify-plugin>=0.2
  Downloading mkdocs-minify-plugin-0.2.1.tar.gz (2.7 kB)
Collecting setuptools>=36
  Downloading setuptools-45.1.0-py3-none-any.whl (583 kB)
     |████████████████████████████████| 583 kB 16.3 MB/s
Collecting MarkupSafe>=0.23
  Downloading MarkupSafe-1.1.1-cp37-cp37m-manylinux1_x86_64.whl (27 kB)
Collecting six
  Downloading six-1.14.0-py2.py3-none-any.whl (10 kB)
Collecting pep562
  Downloading pep562-1.0-py2.py3-none-any.whl (7.0 kB)
Collecting htmlmin>=0.1.4
  Downloading htmlmin-0.1.12.tar.gz (19 kB)
Collecting jsmin>=2.2.2
  Downloading jsmin-2.2.2.tar.gz (12 kB)
ERROR: mkdocs-material 4.6.0 has requirement markdown<3.2, but you'll have markdown 3.2 which is incompatible.

[madmpro]

@madmpro what's important is to understand where this incompatibility issue came from. Are you using any other Markdown extensions besides Material and Pymdown?

My issue was:

ERROR: mkdocs-material 4.6.0 has requirement markdown<3.2, but you'll have markdown 3.2 which is incompatible.
ERROR: mkdocs-material 4.6.0 has requirement pymdown-extensions<6.3,>=6.2, but you'll have pymdown-extensions 6.3 which is incompatible.

[facelessuser]

Don't update Markdown or pymdown-extensions, lock your environment to the previous version and you'll be fine. If material relaxes its requirements, people will also complain about the recent change in code blocks which material will style slightly incorrect. It's a cosmetic change that material wasn't prepared to handled yet, so the theme was locked to not use the next release of Markdown and pymdown-extensions.

[Angelmmiguel]

Done! I've fixed the version in the requirements.txt file and it works perfectly. Thanks for the suggestion @facelessuser

[squidfunk]

Fixed in 92bfb148. I tested all combinations (no code highlighting, CodeHilite, Highlight, with and without Superfences, etc.) and think I catched all cases. I could remove a huge chunk of the CodeHilite-specific CSS which is pretty great. Also upped the dependency versions:

mkdocs>=1.0
mkdocs-minify-plugin>=0.2
Pygments>=2.2
markdown>=3.2
pymdown-extensions>=6.3

Preparing a release right now.

[squidfunk]

Released as part of 4.6.1. If you encounter issues with code block formatting please open a new issue and provide a reproducible case.