Guidelines for languages used in fenced code blocks

[wborn]

There seems to be no consistency in the languages being used for syntax highlighting in fenced code blocks. All languages known to GitHub are listed here.

Here's a list of languages (with links to examples) that I've found being used for syntax highlighting in the documentation so far:

items files

• bash
• java
• xtend

persist files

• java

rules files

• bash
• java
• javascript
• sh
• xtend
• php (Community forum post code fences)

sitemap files

• bash
• java
• perl
• php (Community forum post code fences)

things files

• java
• xtend

shell / Karaf console

• bash
• sh
• shell

Perhaps we can make this a bit more consistent and document the convention in the styleguide? The result can then be used to update the documentation for making the syntax highlighting more consistent. Perhaps you also know of other content that may need some more consistent syntax highlighting?

[Confectrician]

We have a discussion about it in the documentation maintainers area on GitHub.

There was also a clear conclusion on the languages to use.

I will check that and post it here for public discussion.

[wborn]

Does the openHAB website actually use these fenced code block languages @ghys? It seems that code blocks without a language still have syntax highlighting.

Still it makes sense to have proper languages defined for each code block in case this documentation is being (re)viewed/edited on GitHub or in everyone's favorite Markdown editor.

[Confectrician]

I think vuepress decides on its own and doesn't need the languages necessarily.
Anyways we should add languages, in case we have to switch again in the future, even if thats not planned for now.

[Confectrician]

I know it has been a long time, bit i would like to give some updeate here.
Also we should follow the discussion and put some effort in our styleguide.

Just to give a proper overview, i have searched for the definition we made some while ago.

things -> java/perl (some syntaxes break the editor colors)
items/rules -> java
rules -> javascript (better sometimes)
sitemaps -> perl
everything else -> text
bash/shell -> shell

Also @ghys explained how code highlighting was done initally:

On the website code highlighting is performed by highlight.js.
To ease the transition and get a "good-enough" result I put some (poor) heuristics in the config:

openhab-docs/.vuepress/config.js

Line 35 in 1f34da8

md.options.highlight = (str, lang) => {

With this it will automatically detect keywords in the code and set the appropriate language - including 2 custom languages, dsl and rules; it will also perform some mappings and translations for languages encountered in the docs which are not in highlight.js (or called differently).

[lsiepel]

ings -> java/perl (some syntaxes break the editor colors)
items/rules -> java
rules -> javascript (better sometimes)
sitemaps -> perl
everything else -> text
bash/shell -> shell

Can we add this to the developer documentation? somewhere in the readme.md section ?