pawamoy/markdown-exec

Unable to specify the pygments formatter to use on received output

Closed this issue · 5 comments

ssbarnea commented

Describe the bug
Executed problems can produce ANSI output, which mkdocs can render using the ansi pygments formatter.

Still, this plugin does not allow us to specify which formatter to use and uses markdown.

This means that two undesired things will happen when documenting program output:

  • if the output contains ANSI, the rendering will be messed
  • if the output is plain text, some random keywords will be highlighted in the output

To Reproduce
Steps to reproduce the behavior:

  1. Gran a CLI tool that produces ANSI output, like ANSI test file
  2. Add a markdown-exec block the runs it
  3. What the rendered output.

Expected behavior

We need to allow exec to work similarly to already valid ANSI formatter

```ansi
```

Note that while testing, you might miss to see the colors but the ANSI will render fine. If you use inspect, you will see that class colors were added to the HTML and they will render once you add the extra css needed for them.

Screenshots

Example of an ANSI test file using the block above:

Example of undesired markdown coloring on a command line output:

Example of failure to process ANSI escapes:

System (please complete the following information):

  • Markdown Exec version: 1.0.0
  • Python version: 3.11
  • OS: MacOS

Additional context

I did observe that there is already support for recognizing the output as JSON or HTML, so I guess it should not be too hard to add an option where we can declare the expected output format, so it would render correctly.

If you could give some hints on how this can be addressed, I would be happy to contribute a PR. I was quite pleased about the current plugin behavior and its really good documentation.

pawamoy commented

Not sure to understand: isn't the result option working for your use-case?

```bash exec="1" result="ansi"
some-program-that-outputs-ansi
```
pawamoy commented

Did you install a Pygment extension or something? I can't seem to display the colors with an ansi code block (or terminal, or other equivalent languages: https://pygments.org/docs/formatters/).

EDIT: ah, you mentioned extra CSS. Could you share it 🙂 ?
EDIT: nope, can't even see the CSS classes in the HTML 😕

ssbarnea commented

To enable ansi formatting in pygments, you need to install pygments-ansi-color package.

I documented everything I found on 42picky/42picky.github.io#10 -- so if you can review it it, it would be awesome.

So, it is possible to do it, but it needs some changes. Feel free to close the bug if you think we should not do anything more to make it easier for the user.

pawamoy commented

That's great, thanks! I think providing the stylesheet is outside the scope of markdown-exec, but we can definitely put it in the docs.

pawamoy commented

Actually just released v1.2.0 which provides the ansi extra so you don't have to depend on pygments-ansi-color and add the CSS file yourself 🙂