Syntax highlighting for all code on site

[REAS]

We have code in the Reference, Tutorials, and Examples. Ideally, all of the code can have syntax highlighting that is identical to the PDE.

[REAS]

This is our master color coding file: https://github.com/processing/processing/blob/master/java/keywords.txt

[scotthmurray]

I'm researching options, and will document them here.

We could use Pygments (mentioned by @shiffman) for offline syntax highlighting. I am not inclined to do this, just because I don't have the Python skills, and it would complicate our build scripts. Yet, there is an advantage to pre-highlighting everything, rather than forcing it to happen on the client side. (Less JavaScript, faster downloads and page renders for visitors, less bandwidth and server load for us…)

For client-side, JS/CSS-driven options, the best options for us I've found are below. All of these options support basic Java syntax highlighting, but would need customizing to exactly match the keyword highlighting used in Processing.

• Syntax Highlighting in JavaScript (SHJS) — looks solid, but hasn't been updated since ~2008.
• Prism.js — actively developed, solid, but would require us to clean up our HTML (probably a good thing), as code needs to be wrapped inside of <code> elements.
• SyntaxHighlighter — less actively developed, but someone has already made a Processing "brush" (scroll down the page) that perhaps we could adapt. OpenProcessing uses its own "brush" with this highlighter.
• highlight.js — probably my top pick, as it seems cleanest, and it also has Processing support built-in, as of the recent October release!

[shiffman]

I believe @lmccart is using prism.js for https://github.com/lmccart/p5js.org. Lauren, do you have any thoughts / feedback?

[lmccart]

Yes, p5js.org uses prism.js. I think it's about the same as highlight.js, though without Processing support. Highlight.js does not have line numbers, this is likely not a major consideration, we hide them on the p5js.org site anyway.

If you have a processing "brush" or "plugin" already for another library, it should be relatively easy to convert this into one you could use with a different library. All you really need is all the functions and variables together in a regex string. @alignedleft's point about pre-highlighting with Pygments is a good one, but of course the trade off is adding python to the mix.

[lmccart]

I do think it could be worth having <code> tags around code blocks. Though it might just be my nitpicky cs brain telling me that's the "right way", when actually it doesn't matter. It does let you write code symbols without having to worry about them getting incorrectly interpreted when the html is rendered. It is useful for me on the p5js.org site reference because I use these tags to find the bits of code to run live.

Looking at the Processing site, it seems like it would be easy enough to do a find and replace using the <pre> tags to drop in <code> tags as well.

[scotthmurray]

Thanks, Lauren. I agree, this may be a good opportunity to clean up our HTML a bit, and use <code> properly. I'll do some testing with these different tools and report back.

[scotthmurray]

Also, for my future reference, see #4, where @paluka points out he's already made a Processing brush for highlight.js.

[REAS]

I've been manually adding color to the code in the Tutorials and I think it makes a big difference in how the site feels -- it makes the code more friendly for beginners. When we do this, we'll need to back out those changes to the Tutorials. The main parts of the site for this are the Tutorials, the Reference, and the Examples.

[REAS]

Yes, I'm in favor of using https://highlightjs.org/

[jeremydouglass]

It turns out that the new discourse forum runs highlight.js under the hood for syntax highlighting.

However, ironically, it looks like the forum has been misconfigured to not include Processing as a highlighting plugin language, so for the past two years it has been matching Processing code snippets to "cs" which is its older C# highlighter ¯\_(ツ)_/¯

I just switched it over. It looks okay, but really heavy-handed because it formats every built-in function in dark blue. The C# did a lot less but was actually a bit easier on the eyes.

[REAS]

I think it's worth looking into changing the Processing highlighting at the root of highlight.js to match the style in the 3.0 editor. I'd like to use it on the Processing site and now we know it will help the Discourse too.

[REAS]

Here are the relevant highlight.js files: https://github.com/highlightjs/highlight.js/blob/master/src/languages/processing.js https://highlightjs.readthedocs.io/en/latest/style-guide.html https://highlightjs.org/contribute/

Here are the main Processing file: https://github.com/processing/processing/blob/master/java/keywords.txt

And these are the associated colors:

editor.token.comment1.style=#666666,plain
editor.token.comment2.style=#666666,plain
editor.token.function1.style=#006699,plain
editor.token.function2.style=#006699,plain
editor.token.function3.style=#669900,plain
editor.token.function4.style=#006699,bold
editor.token.invalid.style=#666666,bold
editor.token.keyword1.style=#33997e,plain
editor.token.keyword2.style=#33997e,plain
editor.token.keyword3.style=#669900,plain
editor.token.keyword4.style=#d94a7a,plain
editor.token.keyword5.style=#e2661a,plain
editor.token.keyword6.style=#33997e,plain
editor.token.label.style=#666666,bold
editor.token.literal1.style=#7D4793,plain
editor.token.literal2.style=#718a62,plain
editor.token.operator.style=#006699,plain

[jeremydouglass]

The main visibility problem seems to be class=hljs-built_in -- built-ins are really common in Processing, and it is a dark blue that is harder to read, especially in the site's dark mode. Strangely, I don't see "built_in" in the list of associated colors above, but it seems to be mapped to one of the #006699 values -- probably function1, function2, or function4.

https://meta.discourse.org/t/change-highlight-js-styles/44671/3

I thought that perhaps we could use the forum as a testbed for trying out a custom highlight.js style. Unfortunately, it seems like our hosting doesn't allow custom css -- at least, the "Customize > CSS" menu doesn't appear in our admin view.

https://discourse.processing.org/admin/customize/themes

There is also a theme creator plugin that can customize highlight.js themes, but it is not in our list of available plugins.

https://meta.discourse.org/t/codeblock-theme-picker/146396

It seems like the only way we would be able to deploy this via discourse is if the official highlight.js changed and the change was picked up by the discourse plugin. Or if our site host allowed us to use custom css, or install that plugin.

[jeremydouglass]

Actually, we can use the forum as a testbed if we wish.

There are edit locations for each subtheme:

• Admin > Customize > Themes > Default > Edit CSS/HTML
• Admin > Customize > Themes > Dark > Edit CSS/HTML

...and I was able to test overridding a setting with e.g.

.hljs-built_in { color: red !important; }