rust-lang / mdBook

Create book from markdown files. Like Gitbook but implemented in Rust
https://rust-lang.github.io/mdBook/
Mozilla Public License 2.0
18.36k stars 1.65k forks source link

Syntax Highlighting for "JSON with Comments" a.k.a. jsonc #2360

Open harmathy opened 7 months ago

harmathy commented 7 months ago

Problem

In JSON there are no comments allowed. This is also honored by Github syntax highlighting in fenced code blocks:

{
    // Note: there might be additional sizes available
    "sizes": [ "S", "M", "L", "XL", "XXL" ]
}

There is also "JSON with Comments" or jsonc (see [Github language list][1]) which allows C-style comments

{
    // Note: there might be additional sizes available
    "sizes": [ "S", "M", "L", "XL", "XXL" ]
}

This is prominently used in [tsconfig.json][2], [jsconfig.json][3] and [vscode configuration files][4].

It would be nice to have syntax highlighting support for such code blocks.

A code fence with jsonc should be highlighted:

```jsonc
{
    // Note: there might be additional sizes available
    "sizes": [ "S", "M", "L", "XL", "XXL" ]
}


[1]: https://github.com/github-linguist/linguist/blob/4ac734c15a96f9e16fd12330d0cb8de82274f700/lib/linguist/languages.yml#L3220
[2]: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
[3]: https://code.visualstudio.com/docs/languages/jsconfig
[4]: https://code.visualstudio.com/docs/getstarted/settings

### Proposed Solution

* Support for "JSON with Comments" in highlight.js: highlightjs/highlight.js/issues/2016 
  * this adds rendering of C-style comments to normal JSON
* `jsonc` alias also available: highlightjs/highlight.js/issues/4018
  * seemingly not yet contained in a stable release

### Notes

If #2313 is considered, Prism seems to also render comments in "normal" JSON, but there is no `jsonc` alias. 
ehuss commented 7 months ago

As a workaround, I'd recommend using the javascript language tag.

cestef commented 5 months ago

You can also replace mdbook's highlighting engine by overriding it's files in the theme folder. I have a working example with shiki at https://github.com/cestef/rwalk/tree/93b2034657d4e69aa4803941bfeb92f99eab5977/docs/theme. This could pretty much work with any package you like, not sure how prism works though.