Pygments coexisting with JS syntax hightlighting

[jonaprieto]

I want to use syntax highlighting Pygments globally. However,
I do have a few pages that require Highlight.js. As far as I see
in the docs, this use case is not covered, is it?
How can I achieve that? Is it possible?

[berkantsahn]

Hi @jonaprieto ,
I've never done anything like this before, but I can offer this as a suggestion.

You state that some of your pages require Highlight.js
So, In order to do this, you will need to create a structure that will enable Highlight.js to be used

First, create a file named highlight.html in the theme folder and in highlight.html add the required CSS and JS files for Highlight.js,
For example:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.2.0/styles/default.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.2.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>

In your mkdocs.yml file, include highlight.html in all pages using the extra_javascript and extra_css properties. For example:

theme:
    name: 'your-theme'
    extra_javascript:
        - 'theme/highlight.html'
    extra_css:
        - 'theme/highlight.html'

In this way, the highlight.html file is loaded on all pages and Highlight.js is enabled.

You can then enable Highlight.js on specific pages using the highlight.html file. For this process, you need to include the highlight.html file on the page by using the include command in the content of the page.

However, using two different highlighting methods on the same page can cause some compatibility issues, so I recommend using only one highlighting method on your pages.

As I mentioned before, I haven't done anything like this before, but I think it might be useful for you.

[kamilkrzyskow]

I'm not 100% on this, but I assume it's possible to access the instance of the Highlight class from a MkDocs hook and modify the use_pygments variable during the on_page_markdown event and then restore it in the on_page_content event.
The conditional would revolve around a front matter page meta setting like no_pygments: True. You could then use theme extension and extend the extrahead block in your main.html override to add the JavaScript highlight library only to those pages that have the no_pygments meta variable.

I'm unsure about the restoration part, because it might not work if the page events are being run concurrently and share the same Highlight class instance. It might also be the case that the restoration isn't needed at all because each page could be getting their own Highlight class instance. 🤔

[kamilkrzyskow]

@jonaprieto
I was almost correct with my initial assumption. There is no "accessing the Highlight class instance" step. MkDocs creates a new instance of the class for each page between the on_page_markdown and on_page_content events, and it seems that it works sequentially. Therefore you can modify the use_pygments option for the pymdownx.highlight extension, before the instance is created, like I said previously.

WARNING:
The solution below changes the state of the initial config value, and the initial value isn't taken into account at all.
I think that preserving the state isn't really needed, I just made this as a proof of concept ✌️

Example docs:
no_pygments.zip
no_pygments.zip (Removed a redundant if)

Required options in the mkdocs.yml file:

hooks:
    - overrides/.hooks/no_pygments.py

theme:
    custom_dir: overrides
    
markdown_extensions:
    - pymdownx.highlight
    - pymdownx.superfences # required by "pymdownx.highlight" itself

The overrides/.hooks/no_pygments.py hook file looks like this:

from typing import Optional

from mkdocs import plugins
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.structure.pages import Page


@plugins.event_priority(-100)
def on_page_markdown(*_, page: Page, config: MkDocsConfig, **__) -> Optional[str]:
    print("HRY DEBUG on_page_markdown")
    if page.meta and page.meta.get("no_pygments") and "pymdownx.highlight" in config.markdown_extensions:
        if config.mdx_configs.get("pymdownx.highlight") is None:
            config.mdx_configs["pymdownx.highlight"] = {}
        config.mdx_configs["pymdownx.highlight"]["use_pygments"] = False
        print(f"    Disabled Pygments {page.url}")
    return None


@plugins.event_priority(100)
def on_page_content(*_, page: Page, config: MkDocsConfig, **__) -> Optional[str]:
    print("HRY DEBUG on_page_content")
    if page.meta and page.meta.get("no_pygments") and "pymdownx.highlight" in config.markdown_extensions:
        config.mdx_configs["pymdownx.highlight"]["use_pygments"] = True
        print(f"    Enabled Pygments {page.url}")
    return None

The overrides/main.html override looks like this:

{%- extends "base.html" -%}

{%- block extrahead -%}
    {#- Add JavaScript highlighting library -#}
    {%- if page.meta and page.meta.no_pygments -%}
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/default.min.css">
        <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script>
    {%- endif -%}
{%- endblock -%}

{%- block scripts -%}
    {#- Include original content before the additions -#}
    {{- super() -}}

    {#- Highlight code using the JavaScript library -#}
    {%- if page.meta and page.meta.no_pygments -%}
        <script>hljs.highlightAll();</script>
    {%- endif -%}
{%- endblock -%}

The docs/no_pygments.md file has the front matter meta header:

---
no_pygments: True
---

[jonaprieto]

Wow, thanks! let me try this one and back to you if it works.

[kamilkrzyskow]

Oh right, almost forgot to mention. Adding the no_pygments to the front matter idea comes from your docs having a few pages that are different. If a few pages means tens or hundreds possibly in a single directory / section of the page then you can do it differently, than copy pasting the front matter to every file.
As seen in the print(f" Disabled Pygments {page.url}") you can access the url of the page and multiple other things and "filter" it by that.
Another approach could entail using the on_page_read_source event, which allows to read the file on your terms and "pre-process it". You could scan the file looking for the code blocks that are supposed to be handled by the JavaScript highlighter. ✌️

[kamilkrzyskow]

@jonaprieto Come back to me and say it works 🤭 or provide some feedback at least.