Mkdocs-material: highlight.js vs CodeHilite & Pygments

[noraj]

Description

Why bothering with CodeHilite and Pygments when mkdocs officialy and natively supports the much better highlight.js?

See https://www.mkdocs.org/user-guide/styling-your-docs/#mkdocs

Expected behavior

Syntax highlight works out of the box thanks to highlight.js

Actual behavior

Syntax highlight is not working because it requires CodeHilite marodwn extension to be enabled and Pygments python dependency to be installed.

See https://squidfunk.github.io/mkdocs-material/extensions/codehilite

Steps to reproduce the bug

Not relevant.

Package versions

• Python: python --version: Python 3.7.3
• MkDocs: mkdocs --version: mkdocs, version 1.0.4 from /usr/lib/python3.7/site-packages/mkdocs (Python 3.7)
• Material: pip show mkdocs-material | grep -E ^Version: Version: 4.4.0

Project configuration

Not relevant.

System information

• OS: ArchLinux
• Browser: Firefox

[facelessuser]

supports the much better highlight.js

This is a subjective statement. This is simply a matter of preference.

mkdocs officialy and natively supports

The official mkdocs theme official supports it. Mkdocs itself doesn't particularly care what you use.

Highlight.js will pick up on language declarations assuming assume they are specified, which would require you to use CodeHilite even if you don't want to use Pygments. Unless you really only on highlight.js guessing, which can be hit or miss.

It's not too hard to configure CodeHilite to not use Pygments and then include highlight.js via the Mkdocs extra_js option.

Ultimately, it is the theme's choice what to support our of the box. But there is nothing stopping people from using highlight.js.

[facelessuser]

FYI, previous discussion on this: https://github.com/squidfunk/mkdocs-material/issues/1004.

[squidfunk]

I just want to add:

• bigger JavaScript payload
• either a flash of unhighlighted code, especially on slow connections (e.g. emerging markets) or slower critical path rendering - you choose

[noraj]

The official mkdocs theme official supports it. Mkdocs itself doesn't particularly care what you use.

But official mkdocs https://www.mkdocs.org/user-guide/styling-your-docs/ talks about it, this can confuse users.

Highlight.js will pick up on language declarations assuming assume they are specified, which would require you to use CodeHilite even if you don't want to use Pygments. Unless you really only on highlight.js guessing, which can be hit or miss.

That's totally true and due to the "strict" python-markdown implementation using only pure core features (without http autolink, without syntax highlight support (parsing language on code block), etc). but python-markdown is neither fancy out of the box like being GFM compliant so it requires many plugins but is neither really strict or respectful of markdown standards like suing a CommonMark compliant parser.

But that said its true

It's not too hard to configure CodeHilite to not use Pygments and then include highlight.js via the Mkdocs extra_js option.

Based on #1004 issue, can you add a paragraph about using highlight.js.

This is a subjective statement. This is simply a matter of preference.

That's true I was totally subjective but highlights.js is 185 languages, 89 styles and language agnostic when pygment is 300+ lang, ~20 styles and totally python dependent.

---

Any way I'm fine with pygment even if it is python dependant because mkdocs is python anyway. I just asked to know the why.

[squidfunk]

As a side note: if you want a simpler setup without having to manage Python deps by yourself, you can use the Docker container.

[noraj]

@squidfunk Thanks. But hopefully I'm using ArchLinux and some user packaged mkdocs (AUR) and mkdocs-material (AUR) where python-pygments is already listed as a dependency and is in official archlinux community repository.

By the way if you wan to help you could provide an official PKGBUILD in your repo and begin a mkdocs-material (AUR) maintainer or even the official owner.