Mkdocs-material: Markdown 3.2 and Pymdown Extensions 6.3 Released with code block changes

[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

Markdown 3.2 and Pymdown Extensions 6.3 were just released. This forces Pygments code blocks to always be wrapped in code blocks: <div><pre><code></code></pre></div>. This is different that the previous <div><pre></pre></div> convention.

Pymdown already accounts for this in its own documents, and all that was needed is:

  /* Handled pre with wrapped code */
  div.codehilite > pre {
    padding: 0;
  }

If you don't get to it first, I'll try to come up with a pull, but wanted to at least create an issue now.

[squidfunk]

So if I understand correctly, this applies to CodeHilite and Highlight, right? This would mean we could remove a significant amount of CSS, as I always tried to also make the non-Pygments case work. We could then just use pre > code for scoping which would be awesome.

I guess Pymdown adds an explicit dependency for Markdown >= 3,2. Does this in any way conflict with MkDocs?

[madmpro]

requirements.txt in this repo contains an explicit requirement
markdown<3.2

[squidfunk]

@madmpro that is correct. However, I do not yet understand how this causes you trouble, see https://github.com/squidfunk/mkdocs-material/issues/1331#issuecomment-583280548

[madmpro]

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

[itsayellow]

At https://github.com/pipxproject/pipx, we just had our doc build fail with a version conflict because mkdocs-material requires markdown<3.2 (which is why I'm here). I'll try @madmpro's workaround to see if we can get our builds going again.

[thilp]

Hi! I believe I am in the same situation as @itsayellow. I thought it could be useful to highlight the issue with my dependency graph:

mkdocs-material==4.6.0
  - markdown [required: <3.2, installed: 3.2]                # required: <3.2
    - setuptools [required: >=36, installed: 45.1.0]
  - mkdocs [required: >=1, installed: 1.0.4]
    - click [required: >=3.3, installed: 7.0]
    - Jinja2 [required: >=2.7.1, installed: 2.11.1]
      - MarkupSafe [required: >=0.23, installed: 1.1.1]
    - livereload [required: >=2.5.1, installed: 2.6.1]
      - six [required: Any, installed: 1.14.0]
      - tornado [required: Any, installed: 6.0.3]
    - Markdown [required: >=2.3.1, installed: 3.2]
      - setuptools [required: >=36, installed: 45.1.0]
    - PyYAML [required: >=3.10, installed: 5.3]
    - tornado [required: >=5.0, installed: 6.0.3]
  - mkdocs-minify-plugin [required: >=0.2, installed: 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.11.1]
        - MarkupSafe [required: >=0.23, installed: 1.1.1]
      - livereload [required: >=2.5.1, installed: 2.6.1]
        - six [required: Any, installed: 1.14.0]
        - tornado [required: Any, installed: 6.0.3]
      - Markdown [required: >=2.3.1, installed: 3.2]
        - setuptools [required: >=36, installed: 45.1.0]
      - PyYAML [required: >=3.10, installed: 5.3]
      - tornado [required: >=5.0, installed: 6.0.3]
  - Pygments [required: >=2.2, installed: 2.5.2]
  - pymdown-extensions [required: >=6.2,<6.3, installed: 6.3]
    - Markdown [required: >=3.2, installed: 3.2]                        # required: >=3.2
      - setuptools [required: >=36, installed: 45.1.0]

This makes dependency resolution fail (in Pipenv at least). Let me know if this should be dealt with in a different issue, or if I can help in any way! And thanks a lot for mkdocs-material, by the way, it's truly great!

[madmpro]

• pymdown-extensions [required: >=6.2,<6.3, installed: 6.3]
  
  
  
  • Markdown [required: >=3.2, installed: 3.2] # required: >=3.2
  
  

Place the markdown required version in the head of requirements file, or at least, before pymdown-extensions requirement.

[facelessuser]

Let me take a look in venv environment. Depending on how dependencies are installed, there may be a hiccup.

[facelessuser]

Okay, I tested this out in a virtual environment. If you install just mkdocs-material, you will get all the needed requirements and things will work. If you install mkdocs mkdocs-material, mkdocs will be installed first and install the latest Markdown which is incompatible, then it will install mkdocs-material which will cause a failure as the version of Markdown is wrong. For whatever reason, pip will not correct this.

So either just install mkdocs-material and other dependecies not already covered, or ensure you install the correct pymdown-extensions and markdown first:

python -m pip install "pymdown-extensions<6.3" "markdown<3.2" mkdocs mkdocs-material

[facelessuser]

This was intended to avoid complaints, but in the end, it seems crisis could not be averted either way 😞 .

[facelessuser]

If it is easier to relax this and just have peoples code padding off, we could always do that as well. At least in pymdown-extensions, there is a legacy option to revert to the old code block form. But not with CodeHilite 🤷‍♂ .

The alternative is to fix the code padding issue and then relax the requirement.

[facelessuser]

So if I understand correctly, this applies to CodeHilite and Highlight, right? This would mean we could remove a significant amount of CSS, as I always tried to also make the non-Pygments case work. We could then just use pre > code for scoping which would be awesome.

The only place this will not apply is when using table form of code blocks with numbers in the gutter. The content will be <pre><code></code></pre>, but the gutter content will still be special I believe, but for the actually source code, you would be correct.

[waylan]

In case you missed it, as per mkdocs/mkdocs#1970, the next release of MkDocs will require Markdown 3.2. Just thought you guys would want to know that so you can plan for it.

[squidfunk]

Fixed and released as part of 4.6.1 as noted in #1331. If you encounter issues with code block formatting please open a new issue and provide a reproducible case.