bash/sh/shell codeblock syntax highlight

[GSB-Deleven]

Hi,

in VS Code my bash/sh/shell codeblocks look like this:

is there a way to do this in mkdocs-material?

Currently it renders like this:

Thanks a lot for your help

[alexvoss]

This is really a question about the syntax highlighter used. Note that you have two options there, Pygments or a JavaScript highlighter, with Pygments being the default. The Pygments support for bash seems somewhat limited.

You may have more luck using a JavaScript highlighter. Having said that, highlight.js did not fare better with a mount command. I guess they would all work better with actual bash syntax such as for loops, conditionals, etc.?

To be honest, I personally do not find either version particularly helpful. The more colorful rendering that VSCode produces does not exactly clarify things, I think (why are -t and 192.168 both orange?).

[squidfunk]

IIRC, @hellt wrote a custom Pygments Lexer, and it was quite straight forward, wasn't it?

[hellt]

it was moderately straightforward, but still some scripting skills required to put it all together.
in case folks want to get some headstart I documented my journey here.

[squidfunk]

Awesome, thanks for sharing!

[kamilkrzyskow]

I wrote a Pygments lexer myself https://github.com/kamilkrzyskow/gothic-lexer for the Daedalus game scripting language similar to C/C++
Once I finally understood the "sequential tokenization" part, where the root level context switches to function level context and then goes out of it (understanding that part took me a good month or so), then the lexer was done in a week or 2.

@GSB-Deleven can also modify the BashLexer https://github.com/pygments/pygments/blob/master/pygments/lexers/shell.py#L25 as it's probably a good base to start. Or perhaps try the different BashSessionLexer with the console instead of sh, as it seems to be designed with commands in mind. https://pygments.org/docs/lexers/#module-pygments.lexers.shell

[GSB-Deleven]

Thank you very much to all of you.
I'll read in to it and try to figure it out.

Great to have such an active and helpful community/developer

[seub]

Hi all, just adding that I also find the shell syntax highlighting unsatisfying, for example:

Those colors do more harm than good.

[facelessuser]

90% of the time something like console (shell-session, etc.) language works fine for me because I'm not triggering special Bash specific tokens.

But when you trigger certain Bash tokens, it can try to colorize them and be a bit surprising. In the example pyenv local 3.11.15 if you quote the number, it looks okay, but it adds unnecessary steps:

An easy way to overcome this is maybe to write your own simple terminal lexer that highlights the user prompt, entire command, and result as different things, similar to what I showed above but without the Bash nuance. It's not too hard, but I imagine most people don't want to go down that route. I've done some in the past: https://github.com/facelessuser/pymdown-lexers.

Plain texts for a simple command is often sufficient for most people. I can see the lexer approach being more useful if you are often showing actual command prompts with responses and you'd like a visual way to separate the response from the command and avoid the Bash specific nuance.

[seub]

@facelessuser Thank you for the comment and sharing your project! It seems to me solutions such as "quote the numbers" or "use txt" are not ideal, because they don't reflect the intent. I'd hope one day Pygments fixes their highlighting, or I'd be able to choose another highlighter/lexer, and I don't want to remember all the places where I'll need to switch back.

[facelessuser]

To be honest, Bash is a difficult language to highlight correctly. I don't find the VS code example in the opening post much better than the one in MkDocs Material. I personally think a lexer that ignores the nuance of the shell and can target the prompt, user input, and result would be much better, but even in that case, you could still have false positives if the result shows things that mimic the input, but I think it would be better. I don't think you are likely to see a perfect highlighter of such outputs, but I think a more generic one would be better. I don't know if you'll ever see that in Pygments, but who knows.

[hellt]

@facelessuser thanks for the pymdown-lexers, it helped me to understand how to install the lexers in the mkdocs project when I built a custom lexer.
I documented the whole process here https://learn.srlinux.dev/blog/2023/sr-linux-syntax-highlighting-with-pygments

with the flexibility of customer lexers the biggest features I find unsatisfied with mkdocs-material and the surrounding ecosystem are

1. expandable code blocks (full screen view)
2. configurable copy ranges (this is to copy the payload, and not the prompt with it)

[facelessuser]

@hellt Glad you found the lexer project useful. It can be a little confusing when first attempting such things, so it's always nice to have a simple reference. It's awesome that you provided a write up.