Custom Pygments Formatter

[bblanchon]

Hi there!

The built-in extension codehilite allow customizing the Pygments formatter with the pygment_formatter option.
How can I do the same thing with the Hightlight extension?

Best regards,
Benoit

[facelessuser]

You can set configure options in a pygments language here: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/#extended-pygments-lexer-options. I don't know if they offer exactly the same features as codehilite or not, but that is currently what we offer.

[bblanchon]

Thanks for the prompt response, Isaac!
The lexer parses the input, whereas the formatter generates the output.
For example, I replaced the default HtmlFormatter with a LatexFormatter to produce LaTeX code in my project.
I saw nothing related to Pygments formatters in the documentation and the issues.

[facelessuser]

Yes, Highlighter highlights code for HTML output, the output required by Markdown. I do not currently support LatexFormatters. To be fair, I don't support any arbitrary formatters. I'm not quite sure I understand the use case in the context of Markdown. I would need some convincing that it makes sense here and doesn't deserve its own related plugin.

[bblanchon]

I use the LatexFormatter because I convert the whole HTML output to LaTeX for my book.
This is just one example of what you could do with a custom formatter.
You could also use any built-in formatters, such as ImageFormatter.

[facelessuser]

You could also use any built-in formatters, such as ImageFormatter.

There are a number of Pygments formats, and there are also many that make absolutely no sense to use in the context of Markdown parsing. Pygments has formatters for all sorts of environments, like terminal out for instance. I guess, it could be argued there are some niche cases, like your own, that may prefer LaTeX, but those are pretty rare.

It could certainly be done with a custom fence via SuperFences as you could override and call Pygments directly and handle it however you want. Right now we are very much geared towards HTML output. I'm sure some features we support also don't translate to LaTeX (or other formats) output as well.

There are actually a number of Pygments formats that make absolutely no sense to use in the context of Markdown parsing. I guess, it could be argued there are some niche cases, like your own, that may prefer LaTeX, but those are pretty rare.

So right now, the only approach is handling it via something like SuperFences (using a custom fence).

[bblanchon]

Awesome! Custom fences were exactly what I needed!
For the record, here is a simplified version of what I ended up with:

from markdown import Markdown
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import LatexFormatter

def latex_formatter(source, language, css_class, options, md, **kwargs):
    formatter = LatexFormatter()
    lexer = get_lexer_by_name(language)
    output = highlight(source, lexer, formatter)
    return f'<script type="text/x-tex">{output}</script>'

md = Markdown(
    extensions=[
        "pymdownx.superfences",
        ContainerExtension(),
    ],
    extension_configs={
          "pymdownx.superfences": {
              "custom_fences": [
                  {
                      "name": "*",
                      "class": "",  # CAUTION: required
                      "format": latex_formatter,
                  }
              ]
          }
      },
)

Then, of course, I replace the <script> tag with its content in a later processing step to produce the LateX document.

By the way, I think you could make the class field optional.

Thank you very much for your support, Isaac ❤️

[facelessuser]

I'm glad this works well for you! It's generally easier for me to provide the most common cases and empower people with the ability to do whatever else they need with things like custom fences.

By the way, I think you could make the class field optional.

Yeah, that is something we could consider for the future.