mkdocs-material: pymdownx.highlight extension causes crash at startup

Contribution guidelines

I’ve found a bug and checked that …

  • … the problem doesn’t occur with the mkdocs or readthedocs themes
  • … the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
  • … the documentation does not mention anything about my problem
  • … there are no open or closed issues that are related to my problem

Description

I’m trying to get code highlighting to work but when including the documented option to enable, the site crashes

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true

Expected behaviour

The site should start up and code blocs should be highlighted

Actual behaviour

When serving the site, the crashes

mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
ERROR    -  Error reading page 'index.md': format() argument must be a formatter instance, not a class
Traceback (most recent call last):
  File "C:\Python310\lib\site-packages\pygments\__init__.py", line 61, in format
    formatter.format(tokens, realoutfile)
  File "C:\Python310\lib\site-packages\pygments\formatter.py", line 94, in format
    return self.format_unencoded(tokensource, outfile)
  File "C:\Python310\lib\site-packages\pygments\formatters\html.py", line 981, in format_unencoded
    source = self.wrap(source)
TypeError: BlockHtmlFormatter.wrap() missing 1 required positional argument: 'outfile'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "C:\Python310\lib\runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Python310\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Python310\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "C:\Python310\lib\site-packages\click\core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "C:\Python310\lib\site-packages\click\core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "C:\Python310\lib\site-packages\click\core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "C:\Python310\lib\site-packages\click\core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "C:\Python310\lib\site-packages\click\core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "C:\Python310\lib\site-packages\mkdocs\__main__.py", line 181, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "C:\Python310\lib\site-packages\mkdocs\commands\serve.py", line 63, in serve
    config = builder()
  File "C:\Python310\lib\site-packages\mkdocs\commands\serve.py", line 58, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "C:\Python310\lib\site-packages\mkdocs\commands\build.py", line 292, in build
    _populate_page(file.page, config, files, dirty)
  File "C:\Python310\lib\site-packages\mkdocs\commands\build.py", line 174, in _populate_page
    page.render(config, files)
  File "C:\Python310\lib\site-packages\mkdocs\structure\pages.py", line 175, in render
    self.content = md.convert(self.markdown)
  File "C:\Python310\lib\site-packages\markdown\core.py", line 268, in convert
    newRoot = treeprocessor.run(root)
  File "C:\Python310\lib\site-packages\pymdownx\highlight.py", line 491, in run
    code.highlight(
  File "C:\Python310\lib\site-packages\pymdownx\highlight.py", line 392, in highlight
    code = highlight(src, lexer, formatter)
  File "C:\Python310\lib\site-packages\pygments\__init__.py", line 82, in highlight
    return format(lex(code, lexer), formatter, outfile)
  File "C:\Python310\lib\site-packages\pygments\__init__.py", line 69, in format
    raise TypeError('format() argument must be a formatter instance, '
TypeError: format() argument must be a formatter instance, not a class

Steps to reproduce

  1. Create a new docs project
  2. Add provided configuration
  3. Attempt to serve mkdocs serve

Package versions

  • Python: python --version 3.10.2

  • MkDocs: mkdocs --version 1.3.0

  • Material: pip show mkdocs-material | grep -E ^Version 8.2.10

Configuration

site_name: My Site
theme:
  name: material
markdown_extensions:  
  - pymdownx.highlight:
      anchor_linenums: true

System information

  • Operating system: Windows 10
  • Browser: Tested in Brave and Chrome

About this issue

  • Original URL
  • State: closed
  • Created 2 years ago
  • Comments: 37 (26 by maintainers)

Commits related to this issue

Most upvoted comments

I think I found and fixed everything.

I will likely bump Material via PR. If there are issues, I may fix the easy ones, but unfamiliar areas, like maybe code annotations and such, I may defer to you @squidfunk to remedy those changes at your leisure.

This will not guarantee that that there will be no conflicts outside of Material, such as other MkDocs plugins, but we at least now have 8.2.11 which people can pin to if all there requirements are not ready to support the latest Pygments.

Thanks. Beautiful stuff btw 😃

I’ve released 8.2.11 which temporarily pins Pygments and Python Markdown until this issue is resolved, so users can build their documentation projects. As already said, I’ll look into it as soon as I got some time on my hands, but if somebody wants to go ahead and provide a PR, I’m happy to merge. We need to make sure that all code examples still work.