Adding Keywords to a Language at Startup

While normally this should not be necessary, you may find the need to add keywords manually at runtime which are not currently included in a language by default, without touching the original language definition.

Here is a brief guide for the rare case this is needed.

Caveats

• If a language keyword is missing, you should first create an issue or Pull Request to inform the maintainers of highligh.js about this case. By following this procedure, missing keywords can be implemented for regular use.
• Some languages have multiple keywords definitions (inside sub-modes) or even use modes to highlight keywords instead of keywords. There is no true universal way to do this. This works best for simpler grammars with a single top-level keywords section, etc. bash is one such grammar.

Use Cases

• Commands which are provided by an application you install eg in your Linux system like PHP. Here you get the phpenmod and phpdismod commands. These commands are not part of the shell environment, but when you document scripts using the application commands, you may want that these get highlighted too.
• Adding keywords to a language like mathematica can be another reason, if you want to highlight additional expressions manually.
• When you have programmed an own application which you can access in your shell and where you want to show the new command(s) in examples. Highlighting the new commands can improve reading the examples.

How To

The following example is based on adding keywords to the bash language.

Step One

First, take a look on how the keywords structure is created in highlight.js/lib/languages/bash.js.

  return {
    name: 'Bash',
    aliases: ['sh'],
    keywords: {
      $pattern: /\b[a-z._-]+\b/,
      keyword: KEYWORDS,
      literal: LITERALS,
      built_in:[
        ...SHELL_BUILT_INS,
        ...BASH_BUILT_INS,
        // Shell modifiers
        "set",
        "shopt",
        ...ZSH_BUILT_INS,
        ...GNU_CORE_UTILS
      ]
    },

As you can see, the keywords structure has different scopes for different types of keywords: keyword, literal, built_in, etc. Each scope will render the different keywords differently, depending on the theme used.

Step Two

In the example shown below, we are adding keywords to the built_in scope.

Post the last register entry where you load the library and define the languages used, as example:

var hljs = (window.hljs = require('highlight.js/lib/core'))
// ...
hljs.registerLanguage('yaml', require('highlight.js/lib/languages/yaml'))

Add the following: (example keywords used)

const CUSTOM_KEYWORDS = [
  'apt', 'apt-get', 'pecl', 'systemctl', 'service', 'sudo', 'wget', 'tar', 'mysql', 'php', 'grep'];

hljs.getLanguage('bash').keywords.built_in.push(...CUSTOM_KEYWORDS);

This adds the specified custom keywords to the built_in list of keywords.