How can I add a custom language for syntax highlighting in code blocks?

[codethief]

I'm currently preparing a presentation about Zig and would love to use syntax highlighting in code blocks. Unfortunately, highlightjs currently does not support Zig by default but I found a repository with the necessary syntax definitions which I would like to register with highlightjs by including a script tag in my presentation like so:

<script type="module">
import zig from './zig.highlightjs.js'; // local copy of https://notabug.org/Ash/highlightjs-zig/src/master/src/languages/zig.js, served over localhost

hljs.registerLanguage('zig', zig);
</script>

Unfortunately, the global variable hljs is not available. Importing it manually via import hljs from 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/es/highlight.min.js'; doesn't do anything, though, i.e. Zig code blocks will remain "plaintext".

Is there any way I can make this work?

[yhatt]

It's often misunderstood thing: Marp's syntax highlighting with highlight.js is not processed on the browser side, but on Node.js. Trying to extend with a <script> tag (for the browser) is meaningless.

To extend Marp syntax highlighter, you should use Marp CLI with the customized engine.

Unfortunately, highlightjs-zig package does not ready to use in Node.js due to incomatible format for importing pure ESM script. Thus, you have to make some tricks:

// engine.js
const { Marp } = require('@marp-team/marp-core')
const hljs = require('highlight.js')

// highlightjs-zig for static web page is required a globally exposed `hljs` to
// extend highlight.js.
globalThis.hljs = hljs

// Run the script of `highlightjs-zig` for static web page.
//
// `highlightjs-zig` for Node.js is published as ESM only package, but it cannot
// import correctly because it has neither `.mjs` extension or `type: "module"`
// in its `package.json`.
require('highlightjs-zig/dist/zig.min.js')

// Create extended Marp class from an original Marp Core.
class MarpWithHighlightJSZig extends Marp {
  // Overload highlighter to use highlight.js with extended by highlightjs-zig.
  highlighter(code, lang, _attrs) {
    if (lang && hljs.getLanguage(lang)) {
      return hljs.highlight(code, {
        language: lang,
        ignoreIllegals: true,
      }).value
    }
    return ''
  }
}

module.exports = MarpWithHighlightJSZig

npm i --save-dev @marp-team/marp-cli highlightjs-zig
npx marp --engine ./engine.js your-markdown.md

And now, you should be able to see the highlighted zig code block:

[codethief]

You are incredible! Thanks for responding so quickly with such a comprehensive solution! It works perfectly!

[j2deme]

I'm trying to do the same, but using https://github.com/miken32/highlightjs-blade, as highlight.js doesn't support it by default... unfortunately... I don't have the slightest idea of how to start using it 😭

I have a working custom engine, but to be fair, I don't fully understand how does it work...

const container = require("markdown-it-container");
const deflist = require("markdown-it-deflist");

module.exports = ({ marp }) =>
  marp
    .use(({ marpit }) => {
      const { highlighter } = marpit;

      // Override Marp Core's highlighter to wrap each lines by ordered list items
      marpit.highlighter = function (...args) {
        const original = highlighter.apply(this, args);
        const listItems = original
          .split(/\n(?!$)/) // Don't split at the trailing newline
          .map(
            (line) =>
              `<li><span data-marp-line-number></span><span>${line}</span></li>`
          );

        return `<ol>${listItems.join("")}</ol>`;
      };
    })
    .use(container, "danger")
    .use(container, "warning")
    .use(container, "info")
    .use(container, "success")
    .use(container, "primary")
    .use(deflist);

I tried adding the plugin as stated in the project's readme:

var hljs = require('highlight.js');
var hljsBlade = require('highlightjs-blade');

hljs.registerLanguage("blade", hljsBlade);
hljs.highlightAll();

But it only makes Marp fail with an uninformative error [ ERROR ] The specified engine has not resolved.

I also tried the given answer for this issue, but got the same error.

My guess is somewhere around

marp
    .use(({ marpit }) => {
      const { highlighter } = marpit;

      // Override Marp Core's highlighter to wrap each lines by ordered list items
      marpit.highlighter = function (...args) {
        const original = highlighter.apply(this, args);
        const listItems = original
          .split(/\n(?!$)/) // Don't split at the trailing newline
          .map(
            (line) =>
              `<li><span data-marp-line-number></span><span>${line}</span></li>`
          );

        return `<ol>${listItems.join("")}</ol>`;
      };
      // Maybe here 🤔 
    })

As these lines modify the current highlighter, but I don't know how...

What would be the best way to add the plugin to support blade syntax and any other syntax needed and provided by highlight.js? (https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md)

[yhatt]

Some highlight.js extensions are describing how to extend Marp highlighter. Probably the same approach can apply to highlightjs-blade too.
https://github.com/highlightjs/highlightjs-structured-text#marp

[j2deme]

I tried using the code on the linked repo, but it doesn't work with the blade plugin 😞, I think is a matter of the order in which the instructions are given, but I can't get it right.

Without adding any additional plugin, is there a way to customize Marp highlighter to support the additional tags? I mean something similar like the line numbering code? Is it possible?

[yhatt]

@j2deme The following code looks like to work correctly for me. It seems that you've already overriding highlighter method to wrap with list items to add line numbers, so running highlighter with custom instance before it is important.

// engine.js
const hljs = require('highlight.js')
const hljsBlade = require('highlightjs-blade')

hljs.registerLanguage('blade', hljsBlade)

module.exports = ({ marp }) =>
  marp.use(({ marpit }) => {
    marpit.highlighter = function (...args) {
      // First, apply code highlighter with custom instance
      const original = ((code, lang) => {
        if (lang) {
          return hljs.getLanguage(lang)
            ? hljs.highlight(lang, code, true).value
            : ''
        }
        return hljs.highlightAuto(code).value
      })(...args)

      // And wraps the result of highlighting with list tags
      const listItems = original
        .split(/\n(?!$)/) // Don't split at the trailing newline
        .map(
          (line) =>
            `<li><span data-marp-line-number></span><span>${line}</span></li>`
        )

      return `<ol>${listItems.join('')}</ol>`
    }
  })

[j2deme]

Hi, I tried the previous code, but unfortunately it didn't work.

At first I thought it was because of the other plugins I was using, so I commented them, but it didn't work, then I erased everything, and copied and pasted the code you gave me, but I got the same result.

I really don't know why it doesn't work, so I'll have to stay with the current settings of the engine, and keep using PHP syntax to highlight blade snippets.

Thanks for your time trying to get the answer right, if I have some extra time later I'll keep on trying to get it right.