[Help me] Add Chapel highlighting support

[bradcray]

Hi highlight.js developers and experts —

I'm interested in adding support for the Chapel language (https://chapel-lang.org) to highlight.js, and managed to throw together a very simple (but better than nothing) highlighter on my laptop today that is building and rendering properly for me, and I'm looking for helps at next steps. As a disclaimer, this is my first experience with node.js.

At this point I have two main questions:

• At the high level: Reading the various contributing docs, I've ended up confused about whether the best practice is to:

  • file a PR adding chapel.js to the main highlight.js/highlight.js repo...
    • ...under src/languages/ (which is where most languages seem to be?)
    • ...or under extra/... (which is where 3RD_PARTY_QUICK_START.md suggests it should be)
  • request a new Chapel-specific repository under highlight.js (which 3RD_PARTY_QUICK_START.md alludes to?)
  • host it on our repo
    where my main goals is to have our Discourse site support Chapel highlighting and a secondary goal would be to have StackOverflow use it as well.

• At the low level: Though I've been able to do do a Chapel-specific build using node tools/build.js -n chapel and got reasonable output using developer.html, I've been unable to get a scripted all-languages build and test working using the instructions in the various docs, even from a clean copy of the repo that does not contain my changes. E.g., from a copy of the tree in sync with the master/main branch (SHA = 1982c8c), I get:

$ node ./tools/build.js -t node
Starting build.
Finished build.
Writing styles.
Writing package.json.
/Users/bradc/highlight.js/tools/build_node.js:14
    let require = `require('./languages/${lang.name}')`;
                                               ^

TypeError: Cannot read property 'name' of undefined
    at /Users/bradc/highlight.js/tools/build_node.js:14:48
    at Array.map (<anonymous>)
    at buildNodeIndex (/Users/bradc/highlight.js/tools/build_node.js:13:34)
    at Object.buildNode [as build] (/Users/bradc/highlight.js/tools/build_node.js:97:9)
    at async doTarget (/Users/bradc/highlight.js/tools/build.js:87:3)

and a similar result when I use npm run build_and_test

Thanks for any advice with either of these issues.

[bradcray]

PS — Here is the branch I've been working on, for reference: https://github.com/bradcray/highlight.js/tree/chapel-mode

[joshgoebel]

I've ended up confused about whether the best practice is to:

As a 3rd party grammar it will live inside its own repository. You can host it or we can host it here, that's entirely up to you. Take a look at some of the 3rd party repos here for structure. Just one: https://github.com/highlightjs/highlightjs-raku. But you can use pretty much you can use the same structure you're likely already familiar with from the main highlight.js repo, ie src/languages, etc... test/markup, etc...

Then if you want to then use highlight.js to build (and test) your package (and create it's dist CDN JS file - which is recommended) you just need to checkout that repo UNDER your extras folder.

cd highlightjs/extra
git clone your_3rd_party_language_repo
cd ..
node ./tools/build.js -t node # will build a npm package that includes your grammar
# run tests, etc

TypeError: Cannot read property 'name' of undefined

No idea, that's very strange. You could try to add some console logging or debugging to see why languages contains a null or undefined values... I can't see how that could possibly happen with just a quick glance at the code.

[joshgoebel]

where my main goals is to have our Discourse site support Chapel highlighting and a secondary goal would be to have StackOverflow use it as well.

That might be tough, but good luck. Most people don't realize that these major upstream consumers use a VERY particular build of Highlight.js and choose their language subset very carefully (due to size/performance constrains). Just creating a new grammar module (third party or even first party) is no guarantee that any of these major websites will support your language.

[bradcray]

Thanks for the quick responses, @joshgoebel. w.r.t. the TypeError, I had tried hard-resetting my repo to master, but had not gone so far as re-cloning the repo, but when you didn't recognize the error, went to that length and things worked. I think I must have horked something up in my npm/node environment in the original copy of the repo before finding the npm install instructions. Sorry for the distraction there due to my unfamiliarity with node/npm.

Out of curiosity, is there a process for petitioning to incorporate a language into the main repository rather than treating it as a 3rd-party grammar? Or maybe put another way: What determines whether highlight.js treats a language as a 3rd-party grammar vs. one in the main repo?

Thanks again!

[bradcray]

That might be tough, but good luck.

While I agree that the path to getting Chapel highlighting enabled by SO for our tag may be an uphill climb, it appears that Discourse sites do have a hook that permits third-party languages to be enabled, so that's encouraging. Linking here for others who may stumble across this: https://meta.discourse.org/t/hack-to-install-a-new-language-for-highlight-js-on-a-hosted-discourse/55818/7

[joshgoebel]

I’ve just added a hook to our HighlightJS code so now you can use the plugin API to add a custom language for Highlight.JS.

Oh wow, that's completely amazing. :-) Yes, if they allow injecting HTML/JS/CSS (via theme) then yes any "admin" (or whatever) of a Discord site could do this. That's news to both of us. I did not know that. :)

Out of curiosity, is there a process for petitioning to incorporate a language into the main repository rather than treating it as a 3rd-party grammar? Or maybe put another way: What determines whether highlight.js treats a language as a 3rd-party grammar vs. one in the main repo?

Short answer: The core team does not have time to maintain any more languages (review, bugs, support, long-term maintenance, etc.) - we can barely keep up with the ones we have. So therefore, no more first party languages. It's very easy for anyone who desires to use a 3rd party language.

Long answer: #2149

[joshgoebel]

Closing as we have the new PR to track this.