Improve `prism.js` highlighting

[solonovamax]

This PR improves the prism.js highlighting in a couple of minor ways.

• plugin changes:
  • add show-language + toolbar plugins: Shows the language of the current codeblock.
  • add autoloader: Used to automatically load languages.
  • add match-braces: when hovering over a bracket, highlight the matching bracket. Added match-braces class to base.ftl.
  • add diff-highlight: highlight diff codeblocks in conjunction with other languages.
• remove css and javascript languages from being loaded in the main prism.js file.
• Add components directory with all additional prism.js supported languages. These are loaded on-demand by the autoloader plugin.
• Add small transition to the copy code element to match the language toolbar element. (100ms linear transition from 0 -> 100% opacity)
• Fix minor bug in FileWriter causing additional empty directories to be created when copying a folder with a trailing slash.
• Make the diff highlighting look better

[whyoleg]

Hey! Could you describe a bit on your use-cases for most of the changes? Specifically for including support for ±300 languages.

[solonovamax]

Hey! Could you describe a bit on your use-cases for most of the changes? Specifically for including support for ±300 languages.

Here's my usecases/reasons for each of the changes:

• plugin changes:
  • show language: shows the user what language is in use. looks nice.
  • match braces: it looks pretty
  • diff highlight: allows using diff codeblocks paired with language syntax highlighting. also just looks pretty
• remove css & js language from the main prism.js file: they seemed like less important languages to early-load & they exist in the components directly so they're not removed
• add support for the 300-odd languages: I ran into a few cases where I wanted a codeblock in some language that wasn't included by default in dokka, so I included those languages in my project via a custom prism.js script. Then I decided that since I'm adding support for a few languages (the specific ones I needed were toml and groovy), might as well add all of them as others might have a use for it. However, I could very much see an argument for wanting to prune it down to the following list & removing all the other ones
  • config formats (xml, toml, json, etc.)
  • scripting languages (bash, batch, zsh, etc.)
  • jvm languages (java, kotlin, groovy, possibly scala)
  • possibly a few other random languages (eg. css & other stuff)
• transition for copy code button: it looks pretty + it makes it match the language toolbar
• file writer bug: ran into it while adding code to include the components directory
• diff highlighting: it looks pretty

not sure how many languages would be left after pruning them, but it'd probably be much less.

[adam-enko]

Hi, I really like the idea of adding more styling support, but I have some concerns about adding so many files.

Adding these files introduces maintenance and testing requirements on the Dokka team. Dokka has a slow release cycle. so I think it's likely that these scripts would become outdated.

Adding these files could interfere with users who want to use a different highlighting library. Dokka has support for adding custom scripts for each project, so couldn't adding these be done per-project, rather than as a Dokka default? Although I think Dokka could make this easier, maybe with a Gradle or Dokka plugin?

[solonovamax]

Hi, I really like the idea of adding more styling support, but I have some concerns about adding so many files.

I'm going to look at pruning a bunch of the niche languages. hopefully that should substantially decrease the file count.

Adding these files introduces maintenance and testing requirements on the Dokka team. Dokka has a slow release cycle. so I think it's likely that these scripts would become outdated.

the last time prism.js was updated was august 23, 2022, so I don't think that's an issue.

Adding these files could interfere with users who want to use a different highlighting library.

how would it interfere with users any more than the current prism.js highlighter in dokka?

Dokka has support for adding custom scripts for each project, so couldn't adding these be done per-project, rather than as a Dokka default? Although I think Dokka could make this easier, maybe with a Gradle or Dokka plugin?

yeah, it could be done per-project, but it's also kinda annoying to have to check in a bunch of js files to vcs if dokka could just have the most common ones.

[solonovamax]

Alright, I've gone through and pruned some of the less popular languages from 297 languages down to 114 languages.

Are there any other languages I should remove as well? I tried to keep it mostly to popular/useful things that someone might use.

Another alternative could be to change from prism.js altogether and instead use a compile-time syntax highlighter.

I've also rebased on top of master to ensure there were no merge conflicts.

[solonovamax]

Any update on this?

[solonovamax]

I've dropped it down to only 91 languages rather than the original 300-odd languages

[solonovamax]

hey, any updates for this?

[whyoleg]

Hey! Sorry for the delay, we are busy with preparation for Dokka 2.0.0 and beyond :) I've recently answered in slack

thanks for pinging, but it will be not possible to do it in 2.0 scope Soon, some HTML changes which are already properly tested will be merged in master, and so it would take some time to test those changes again But still, I think that some of changes could be a nice addition. I'm still very sceptic about adding support for additional languages highlighting so I think it would be nice to start without them Could you update (or create new) PR with removing changes with all those additional languages? It would also help to speed-up review if you will provide screenshots with before and after with description of what is changed Thank you!

let's continue discussion here, so that it will be easier to track it

[solonovamax]

I'm still very sceptic about adding support for additional languages highlighting so I think it would be nice to start without them

sorry, just got around to this now, but if you want I could aggressively prune the list of languages down to the following ones:

• markup (dependency)
• clike (dependency)
• javascript
• diff (dependency)
• gradle
• groovy
• java
• javadoc
• javadoclike (dependency)
• json
• kotlin
• properties
• toml
• yaml

I specifically include gradle, groovy, and toml in there for putting examples of how to add a dependency on the project in the documentation (example), and properties, json, and yaml were added because they're common configuration formats.

the original list of languages was

• markup (dependency)
• css
• clike (dependency)
• javascript
• java
• javadoc
• javadoclike (dependency)
• kotlin