Where should I add the code for a custom directive?

[vmgustavo]

It is not clear how to add the custom directive code in this page https://marpit.marp.app/directives?id=custom-directives
How should I do it? Is there any other page that explains it?

[yhatt]

Marpit instance has customDirectives.global and customDirectives.local object to allow adding directives as you like.

The example code is assuming to have marpit instance. This is a full example:

import { Marpit } from '@marp-team/marpit'

const marpit = new Marpit()

// Define $theme global directive for aliasing to theme directive
marpit.customDirectives.global.$theme = (value) => {
  return { theme: value }
}

// Define colorPreset local directive for setting multiple local directives at once
marpit.customDirectives.local.colorPreset = (value) => {
  switch (value) {
    case 'sunset':
      return { backgroundColor: '#e62e00', color: '#fffff2' }
    case 'dark':
      return { backgroundColor: '#303033', color: '#f8f8ff' }
    default:
      return {}
  }
}

// Render Markdown, and use the result as you like :)
const { html, css } = marpit.render(`
<!-- $theme: foobar -->
<!-- colorPreset: sunset -->

...
`)

[vmgustavo]

The example code is assuming to have marpit instance

I am quite new to this, what is a marpit instance?

[yhatt]

If you had followed the usage of Marpit, you already should have made an instance of Marpit class.

[OlegHahm]

I'm struggling to understand this example. I'm running marp-cli to create HTML slides from my markdown file. My understanding so far is, that marp-cli will by default use the Marp-Core as engine. Is there a way to extend this engine by custom directives?

[yhatt]

Marp Core class is an inherited class from Marpit class, so Marp Core instance is also a Marpit instance (See also the architecture diagram in the project contributing guideline). Thus, a way to define custom directives is exactly same as Marpit.

As described at Marp CLI documentation, the custom engine for Marp CLI should return an instance of Marpit (= also allowed Marp Core instance) created by the constructor option passed as the first argument of the function.

// engine.mjs
import { Marp } from '@marp-team/marp-core'

export default (constructorOptions) => {
  // Create Marp instance, from options passed as the first argument of the functional engine
  const marp = new Marp(constructorOptions);

  // Define custom directives to the created instance
  marp.customDirectives.local.colorPreset = (value) => {
    // ...
  };

  // And return a modified instance
  return marp;
}

Note

For just extending Marp CLI's built-in Marp Core, you don't need create an instance from scratch. You can pick up a prepared Marp instance through marp getter.

export default ({ marp }) => {
  marp.customDirectives.local.colorPreset = (value) => {
    // ...
  };

  return marp;
}

[OlegHahm]

Great, thanks a bunch!