Steps for adding a new custom markdown syntax

[mil-ad]

I'm diving deeper into customising my marp setup and now I'm trying to add new markdown syntax to my slide deck.

For instance let's say I want to add ** which behaves like a normal list item with some extra CSS attached to it. I believe this is where markdown-it comes into play but I'm having a hard time wrapping my head around all the different pieces (marp vs marp-it vs marp-core vs marp-cli).

Is what I'm trying to do possible? If yes are there good examples/guides/starting point for I should be roughly doing?

[yhatt]

Of course. Marp has been maximized compatibility with markdown-it plugin ecosystem, so a way to extend Markdown syntax is exactly same as markdown-it. In the most cases, any Marp knowledgements are not required to make a plugin for extending syntax.

Useful resources:

• markdown-it docs for plugin developers
• Notes on Markdown-it and Building a Plugin | Joshua's Docs

The following snippets are how to test your plugin in Marp CLI (with customized engine):

// engine.js
// https://github.com/marp-team/marp-cli#functional-engine

const yourMarkdownItPlugin = (md) => {
  // Write markdown-it plugin for extending Markdown syntax as you like
}

module.exports = ({ marp }) => marp.use(yourMarkdownItPlugin)

marp --engine ./engine.js your-markdown.md

If met a situation to require manipulating something of Marp-specifics, e.g. slides, the first thing to do is reading Marpit API references. You can see details about public interface of Marpit instance and a bunch of internal markdown-it plugins. (Yes, actually Marp is consisted of a lot of markdown-it plugins!)

In addition, reading source code of Marpit and Marp Core would be helpful to know how we are making some advanced features.

If confused about relations of Marp libraries, see the diagram about the architecutre at the contributing guideline.