[Maintainers]: Please update your 3rd party grammar repo to the latest spec

To ensure your grammar continues to function smoothly with future releases of Highlight.js you may need to make a few small changes. The good news is you can make all these changes today - and your grammar will continue to work with the v10 build system as well. You’ll just be ready for v11 early.

Following our official spec makes it easy to generate a CDN ready dist folder and also allows advanced users/integrators to build custom versions of Highlight.js that include your grammar in the main minified bundle with very little effort.

If you have some disagreement with the official spec or build process (and would also like to invest your time in finding a better solution) please continue that discussion here: Improving testing / integration / usage for 3rd party grammars This is not the thread for that larger discussion.

That topic died because at the time no one seemed interested in discussing or working on it.

So is v11 changing how 3rd party grammars work or are built?

Not really. Some early 3rd party grammars (perhaps your own) were invented side-by-side with the official spec and have always done things a “bit differently”. The v10 build system thus has several hacks to “accommodate” these early grammars - allowing them to work as-is. These hacks will be removed from the v11 build system, requiring all grammar modules to provide a single export that can be understood by the Highlight.js build system (rollup).

Summary

• Your primary JS file should set only the default export, nothing further.
  • ie, either export default or module.exports = ...
  • this means no more definer exports, your primary JS file should not worry about the web browser context, that is what the dist CDN builds are for
  • no more shims: var module = module ? module : {};
• Your repository should include a dist folder with a CDN ready build of your grammar (built using the Highlight.js build system) See 3RD_PARTY_QUICK_START.md.md

An example grammar already meeting all requirements:

• https://github.com/highlightjs/highlightjs-robots-txt/
• https://github.com/highlightjs/highlightjs-robots-txt/blob/master/src/robots-txt.js

Spec Checklist

You can copy this template into your own project’s issues area on GitHub:

- [ ] Your primary JS file should only set a default export, no others
- [ ] Remove any other definer and/or other additional exports
- [ ] Your repository should include a `dist` folder with pre-built CDN assets. Reference: [3RD_PARTY_QUICK_START.md.md](https://github.com/highlightjs/highlight.js/blob/master/extra/3RD_PARTY_QUICK_START.md)
- [ ] Remove any browser shims from your raw JS source
- [ ] Consider adding a `package.json` and publishing your grammar on [NPM](https://www.npmjs.com) if you aren't already
- [ ] Please update your `README.md` if necessary to reflect these changes
- [ ] Remove `charset="UTF-8"` from your examples, it should no longer be necessary with `dist` builds produced by our build tools

---

Browser shims

If your grammar has any shims like:

var module = module ? module : {};     // shim for browser use

Remove the shims entirely. The dist CDN distributable is meant to solve this issue.

---

Simply export default

If you have a very specifically named define function:

function hljsDefineRpmSpecfile(hljs) {
  return {
    name: "RPM specfile"

This isn’t necessary. It’s actually not necessary to name this function at all.

What a simple export looks like (ES modules):

export default function(hljs) {
  return {
    name: "RPM specfile"

What a simple export looks like (CJS):

module.exports = function (hljs) {
  return {
    name: "RPM specfile"

Whether you use ES or CJS may depend on how you expect node users to use your library (and whether you still want to support Node v10). The Highlight.js build system can build CDN distributable regardless of whether your source is in ES module or CJS format.

---

Exporting other things

If your grammar main JS file includes code like:

module.exports = function(hljs) {
    hljs.registerLanguage('rpm-specfile', hljsDefineRpmSpecfile);
};

module.exports.definer = hljsDefineRpmSpecfile;

All this boilerplates can be removed. This is what the CDN ready distributable in dist does for you, handles browser concerns. Just remove all this and export the single function, as shown above.

[joshgoebel]

Closing this as we’ve decided to have a slightly hands-off approach with 3rd party grammars going forward. If the grammar isn’t in core and isn’t causing any problems then we plain to be less concerned with how these repos are setup, structured, etc. There may be exceptions (some unusual circumstance, support burden, security issue, etc) but for now do as you feel best…

Feel free to close the issues I’ve opened (or not). The “official” approach is still recommended (for allowing users to easily build your grammar into a monolith using our build tools - and for the additional security scanning our build system provides), but I’m not going to try and force it on anyone anymore. If any of you might be interested in working on a GitHub action to make it easier to automate builds (with our security scanning) for those desiring them, get it touch.

CC @highlightjs/grammar-maintainers CC @highlightjs/core

Thank you all again so very much for contributing in the first place. 😃

---

For PR requests to add a new 3rd party grammar to ADDITIONAL_LANGUAGES I think we’ll only enforce some simple usability requirements:

• A minimal useful README showing how to use the grammar (or linking to such docs)
• A mention of which versions of Highlight.js the grammar it works with

[StoneCypher]

Is it really good practice to include build artifacts like dist in the repository? I have personally always avoided this in the projects I maintain.

That’s what dist means traditionally. It’s the build products included in distribution.

If it shouldn’t be in the distribution, it shouldn’t be in dist. Kind of like how if it’s in build it definitely should not be.

In a standard setup, the distribution is often just src, the pre-builds that someone wants on CDN in dist (often just the minified bundled single es6,) package, package-lock, and the README