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: https://github.com/openhab/openhab-docs/blob/1f34da84f5f077b45bf55031f47f35b4c11f06fd/.vuepress/config.js#L35 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 ?

[Skinah]

@lsiepel Is it possible to instead add it to:

Code analysis report.html Spotless syntax checking method

This way it removes the load off of a volunteer reviewer and also directs anger towards a bot and also hopefully it gets noticed sooner by a dev.

Also as a separate suggestion, can a bot make an automatic post on any new PR with Initial Contribution flagged to ask the person to check the Code analysis report.html and remove all warnings whilst they wait for a reviewer? Also it could list any recently changed dev rules with links to documentation.

[stefan-hoehn]

@wborn Wouter, this is already a few years old - can we find a solution for that? What do you think about the ideas of the participants of the conversation? I would love if we finally can make a decision and close this. WDYT?

[lsiepel]

Regarding the code fences, if at all possible, the best possible solution can warn that a code fence is missing code type. It can’t determine the code type to use. If I remember correctly @Confectrician was looking into some linting stuff a while ago. Maybe this can be added too.

[wborn]

I think this issue can be closed when https://github.com/openhab/openhab-docs/issues/999#issuecomment-1336405364 is documented. It should technically be possible to detect the language of the code most of the time and add SAT findings.