Mkdocs-material: Yaml Code highlite

[shinji62]

Description

Hi,

I am using the last Docker images, and I try to get my Yaml code highlighted but seems not working.

Here my mkdocs.yml

site_name: test
theme:
  name: 'material'
  palette:
    primary: 'blue'
    accent: 'blue'

markdown_extensions:
  - codehilite
  - admonition
  - pymdownx.details
  - pymdownx.critic
  - pymdownx.superfences
  - pymdownx.mark

pages:
- 'Home': index.md
- 'Requirements': Requirements.md

[squidfunk]

Please share some more information, i.e. a reproducible scenario, so we can help you efficiently. Highlighting works on the official docs, so it's probably misusage or misconfiguration.

[shinji62]

Ok in the code I am using something like this

I got

was expecting to got something like

- put: resource-deploy-web-app
  params:
    manifest: build-output/manifest.yml

[facelessuser]

It's technically highlighting the YAML code, and what I mean is that it is being sent through pygments, and is being identified as YAML, and the pieces are getting appropriate classes:

<div class="codehilite" id="__code_0"><button class="md-clipboard" title="Copy to clipboard" data-clipboard-target="#__code_0 pre, #__code_0 code"><span class="md-clipboard__message"></span></button><pre><span></span><span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">put</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">resource-deploy-web-app</span>
  <span class="l l-Scalar l-Scalar-Plain">params</span><span class="p p-Indicator">:</span>
    <span class="l l-Scalar l-Scalar-Plain">manifest</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">build-output/manifest.yml</span>
</pre></div>

The problem is that the provided color scheme just isn't doing much with the classes. You could target the YAML specific classes (l-Scalar etc.) to provide better highlighting, but you can see Pygments demo doesn't add any real color either, just enter your example on their demo page: http://pygments.org/demo/.

[shinji62]

How can I provided the class within my code block ?

Thanks

[facelessuser]

I'm going to guess that the Pygments theme provided with Material is derived from a built-in theme to some extent, or maybe another theme that was derived from a built-in theme. I believe that most (if not all) of Pygment's built-in, provided themes really only target the basic classes, and not language specific classes (such as YAML's l-Scalar).

It doesn't make sense to target classes l and p for a lot of languages as it may make the highlighting too busy, but in YAML, it may be desired to highlight such values, and because of that, YAML specific classes are provided.

I'm pretty sure there are other languages that Pygments supports that do similar things like YAML is doing. You just have to extend the color scheme to highlight those language specific things if it makes sense.

Hopefully that at least clarifies what is happening a little better. I'm not sure if this is something Material specifically wants to address in its provided color scheme, or if this is something that users should just tweak in their own CSS, I'm more aiming to explain what is happening.

[squidfunk]

Pygments doesn't parse literal values any different than keys, so there's no real possibility for styling. This is the reason why the official Material documentation wraps every YAML value in quotes, because then values can be styled differently.

[facelessuser]

@shinji62 I'm not sure what you mean by this question:

How can I provided the class within my code block ?

Pygments is most likely already doing this. What I posted above is the actual HTML that is being output, but even with this, my highlighting is just black text because the CSS doesn't provide special colors for the specific classes.

[shinji62]

Ok so nothing I can do.

[facelessuser]

I'd echo what @squidfunk says, taking a closer look, both the key and value of the YAML dictionaries are classed with l-Scalar, so there isn't any real distinguishing classes.

[facelessuser]

You could use a JavaScript highlight instead.

[shinji62]

How can I do that ? @facelessuser

[martinbira]

@shinji62

Just change the highligting language, change "yml" to "javascript"

[facelessuser]

@markainick, that isn't what I meant. I meant, don't use Pygments, but instead use a JavaScript based syntax highlighter like highlight.js or something else. You'd have to disable pygments use in things like CodeHilite. You'd have to look at their documentation and use the appropriate option. Then you'd have to include the JS highlighter and theme of your choice, and possible configuration. I unfortunately don't have a step by step guide handy at this moment.

In short, there are only three options:

• Accept that Pygments isn't going to highlight yaml like you like. It does highlight certain things in yaml, but maybe just not to the level you are used to. This is fine for me in my projects, but I can understand that it may bother some people.
• Quote your keys to make them different like @squidfunk, suggested. This isn't ideal as it forces you to present yaml in a very specific way for the sake of highlighting, but there is nothing wrong with this approach.
• Or use a different highlighter than Pygments. You'll have to disable Pygments use in Python Markdown extensions that are applicable and references the JS highlighter's documentation of your choice to see how to include and use it.

[squidfunk]

Thanks @facelessuser for taking care of this! Closing as answered.

[shinji62]

Guys,

i try to disable pygments like

markdown_extensions:
  - codehilite:
      use_pygments: false
      guess_lang: false

Then I add

extra_javascript:
  - 'assets/js/highlight/highlight.pack.js'

extra_css:
  -  'assets/js/highlight/styles/agate.css'

to mkdocs but now, no more highlighting.
Not sure what I did wrong ..

[facelessuser]

@shinji62, check out highlight.js's usage documentation, they specifically cover how to enable highlighting: https://highlightjs.org/usage/.

You need to call initHighlightingOnLoad:

<link rel="stylesheet" href="/path/to/styles/default.css">
<script src="/path/to/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

Personally, I'd use a style that works with Materials code background as well since agate is a dark theme, but Material adds light backgrounds for a light theme. Something like atom-one-light.css might work better for you, or you'd have to add some additional CSS to make the code backgrounds dark.

[shinji62]

@facelessuser Thanks, I am very new to mkdocs.. so eve not ssure where I should but this line.

[facelessuser]

@shinji62, you should put it in a local JavaScript file that you include in mkdocs.yml after highlight.pack.js.

[shinji62]

It works !!!! Thanks !!!!!!