Admonition blocks don't show up

[csandanov]

I had freezed markdown==2.6.7 and everything worked fine but recently mkdocs-material required to install newer tornado version that wasn't compatible with 2.6.7. After I unfreeze markdown, adminition blocks no longer render.

Article with adminition blocks: https://wodby.com/stacks/php/docs/local/quick-start/ Build on wercker: https://app.wercker.com/Wodby/php-docs/runs My mkdocs.yml: https://github.com/wodby/php-docs/blob/master/mkdocs.yml

Packages I install via pip:

pip install mkdocs mkdocs-material markdown markdown-include pygments

[squidfunk]

Thanks for your submission. Can you please provide a minimal reproducible example including a mkdocs.yml and what steps exactly you performed that led to the issue?

[csandanov]

This problem started after I unfreezed pip packages because my build failed.

Looking at the history of my builds I see that I changed only markdown files when (Mar 29th) the build started to fail:

pip install mkdocs mkdocs-material tornado==4.4.2 markdown==2.6.7 markdown-include pygments
mkdocs build

with the following error:

Collecting mkdocs
  Downloading mkdocs-0.17.3-py2.py3-none-any.whl (1.2MB)
Collecting mkdocs-material
  Downloading mkdocs_material-2.7.1-py2.py3-none-any.whl (124kB)
Collecting tornado==4.4.2
  Downloading tornado-4.4.2.tar.gz (460kB)
Collecting markdown==2.6.7
  Downloading Markdown-2.6.7.tar.gz (303kB)
Collecting markdown-include
  Downloading markdown-include-0.5.1.tar.gz
Collecting pygments
  Downloading Pygments-2.2.0-py2.py3-none-any.whl (841kB)
Collecting livereload>=2.5.1 (from mkdocs)
  Downloading livereload-2.5.1-py2-none-any.whl
Collecting PyYAML>=3.10 (from mkdocs)
  Downloading PyYAML-3.12.tar.gz (253kB)
Collecting click>=3.3 (from mkdocs)
  Downloading click-6.7-py2.py3-none-any.whl (71kB)
Collecting Jinja2>=2.7.1 (from mkdocs)
  Downloading Jinja2-2.10-py2.py3-none-any.whl (126kB)
Collecting pymdown-extensions>=3.4 (from mkdocs-material)
  Downloading pymdown_extensions-4.9.2-py2.py3-none-any.whl (205kB)
Collecting singledispatch (from tornado==4.4.2)
  Downloading singledispatch-3.4.0.3-py2.py3-none-any.whl
Collecting certifi (from tornado==4.4.2)
  Downloading certifi-2018.1.18-py2.py3-none-any.whl (151kB)
Collecting backports_abc>=0.4 (from tornado==4.4.2)
  Downloading backports_abc-0.5-py2.py3-none-any.whl
Collecting six (from livereload>=2.5.1->mkdocs)
  Downloading six-1.11.0-py2.py3-none-any.whl
Collecting MarkupSafe>=0.23 (from Jinja2>=2.7.1->mkdocs)
  Downloading MarkupSafe-1.0.tar.gz
Building wheels for collected packages: tornado, markdown, markdown-include, PyYAML, MarkupSafe
  Running setup.py bdist_wheel for tornado: started
  Running setup.py bdist_wheel for tornado: finished with status 'done'
  Stored in directory: /root/.cache/pip/wheels/b3/db/47/46e05d1ee3ecfba252fcab42f0a156dab0df0cddf99fa0827c
  Running setup.py bdist_wheel for markdown: started
  Running setup.py bdist_wheel for markdown: finished with status 'done'
  Stored in directory: /root/.cache/pip/wheels/6a/65/b5/e9ec64331503edca55cbc421160f8c5adcbe8b2f28b9ba6e99
  Running setup.py bdist_wheel for markdown-include: started
  Running setup.py bdist_wheel for markdown-include: finished with status 'done'
  Stored in directory: /root/.cache/pip/wheels/22/00/ef/54224b89648bfe180fb38a713cd142e1a38b9b381513ea3115
  Running setup.py bdist_wheel for PyYAML: started
  Running setup.py bdist_wheel for PyYAML: finished with status 'done'
  Stored in directory: /root/.cache/pip/wheels/2c/f7/79/13f3a12cd723892437c0cfbde1230ab4d82947ff7b3839a4fc
  Running setup.py bdist_wheel for MarkupSafe: started
  Running setup.py bdist_wheel for MarkupSafe: finished with status 'done'
  Stored in directory: /root/.cache/pip/wheels/88/a7/30/e39a54a87bcbe25308fa3ca64e8ddc75d9b3e5afa21ee32d57
Successfully built tornado markdown markdown-include PyYAML MarkupSafe
Installing collected packages: six, singledispatch, certifi, backports-abc, tornado, livereload, PyYAML, markdown, click, MarkupSafe, Jinja2, mkdocs, pymdown-extensions, pygments, mkdocs-material, markdown-include
Successfully installed Jinja2-2.10 MarkupSafe-1.0 PyYAML-3.12 backports-abc-0.5 certifi-2018.1.18 click-6.7 livereload-2.5.1 markdown-2.6.7 markdown-include-0.5.1 mkdocs-0.17.3 mkdocs-material-2.7.1 pygments-2.2.0 pymdown-extensions-4.9.2 singledispatch-3.4.0.3 six-1.11.0 tornado-4.4.2
fetch http://dl-cdn.alpinelinux.org/alpine/v3.7/main/x86_64/APKINDEX.tar.gz
fetch http://dl-cdn.alpinelinux.org/alpine/v3.7/community/x86_64/APKINDEX.tar.gz
(1/2) Installing pkgconf (1.3.10-r0)
(2/2) Installing bash (4.4.19-r1)
Executing bash-4.4.19-r1.post-install
Executing busybox-1.27.2-r7.trigger
OK: 31 MiB in 35 packages
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 11, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python2.7/site-packages/click/core.py", line 722, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python2.7/site-packages/click/core.py", line 697, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python2.7/site-packages/click/core.py", line 1066, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python2.7/site-packages/click/core.py", line 895, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python2.7/site-packages/click/core.py", line 535, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python2.7/site-packages/mkdocs/__main__.py", line 155, in build_command
    site_dir=site_dir
  File "/usr/local/lib/python2.7/site-packages/mkdocs/config/base.py", line 181, in load_config
    errors, warnings = cfg.validate()
  File "/usr/local/lib/python2.7/site-packages/mkdocs/config/base.py", line 105, in validate
    post_failed, post_warnings = self._post_validate()
  File "/usr/local/lib/python2.7/site-packages/mkdocs/config/base.py", line 85, in _post_validate
    config_option.post_validation(self, key_name=key)
  File "/usr/local/lib/python2.7/site-packages/mkdocs/config/config_options.py", line 433, in post_validation
    config[key_name] = theme.Theme(**theme_config)
  File "/usr/local/lib/python2.7/site-packages/mkdocs/theme.py", line 47, in __init__
    self._load_theme_config(name)
  File "/usr/local/lib/python2.7/site-packages/mkdocs/theme.py", line 77, in _load_theme_config
    theme_dir = utils.get_theme_dir(name)
  File "/usr/local/lib/python2.7/site-packages/mkdocs/utils/__init__.py", line 373, in get_theme_dir
    return os.path.dirname(os.path.abspath(theme.load().__file__))
  File "/usr/local/lib/python2.7/site-packages/pkg_resources/__init__.py", line 2323, in load
    self.require(*args, **kwargs)
  File "/usr/local/lib/python2.7/site-packages/pkg_resources/__init__.py", line 2346, in require
    items = working_set.resolve(reqs, env, installer, extras=self.extras)
  File "/usr/local/lib/python2.7/site-packages/pkg_resources/__init__.py", line 783, in resolve
    raise VersionConflict(dist, req).with_context(dependent_req)
pkg_resources.ContextualVersionConflict: (Markdown 2.6.7 (/usr/local/lib/python2.7/site-packages), Requirement.parse('Markdown>=2.6.10'), set(['pymdown-extensions']))

As you can see pymdown-extensions started to require markdown >= 2.6.10.

[facelessuser]

Yes, your builds started failing because pymdown-extensions requires Python Markdown 2.6.10 now. This was because some contributors noticed that the pymdown-extensions CI tests were testing features/fixes that were only available in 2.6.10 (even if the extension doesn't specifically need the latest version of Python markdown to work). I decided to up the minimum version so avoid testing confusion.

As for your Admonitions, there were some fixes to Admonitions in the latest Python Markdown. In short, it is has fixed some issues where it would allow bad syntax.

So looking at the file you referenced, I see:

!!! danger "Persistence of database data":
    You will lose MariaDB / PostgreSQL data if you run `docker-compose down`. Instead use `docker-compose stop` to stop containers. Alternatively, you can use a manual volume for mariadb data (see compose file), this way your data will always persist. 

Looking at the Admonition extension's documentation, you can see the syntax it expects:

!!! type "optional explicit title within double quotes"
    Any number of other indented markdown elements.

    This is the second paragraph.

Notice there is no : following the header. It is possible that Admonitions used to allow : by accident in the past, but the documentation clearly states the format is !!!, followed by the class, and then the title in quotes. There is no mention of : being allowed.

[squidfunk]

@facelessuser: thanks for the explanation! Does it mean we should pin Markdown to >= 2.6.10 or just up the Pymdown-Extensions version?

[csandanov]

@facelessuser thank you! after removing : at the end blocked showed up, I'm pretty sure I copied an example from somewhere with : though

[facelessuser]

@squidfunk Picking up fixes is always good. Pymdown-extensions requires the latest, so you'd indirectly require it just by bumping to the latest pymdown-extensions. But either way works.

Really, this issue boils down to bad syntax on the user's part, but it may save you future issues if Python Markdown doesn't allow the bad syntax moving forward.

[facelessuser]

@csandanov, yes, it wouldn't surprise me if other users unknowingly do what you did since it never caused failures, so I can easily see their being bad examples out there. One thing I'm sure of though is that the admonition documentation has never shown examples with :. I've been using it for years.