markdown-macros

Table of contents

• 🍵 Introduction
• 🚀 Get started
• 🛠️ Usage
  • remark
  • markdown-it
  • marked
• 🤝 Contribute
• 👑 Author
• ⚖️ License
• 📰 Changelog

🍵 Introduction

This library was designed to run macros within Markdown content, but it can be used for any other text-based content. It relies on a specific syntax (@MACRO:) that you can use to execute your own logic, perform text replacements, generate Markdown content, and more.

It provides a comprehensive and fully typed API with TypeScript, as well as plugins for remark, markdown-it, and marked.

⚠ Note that when using these plugins, the library will act as a preprocessor!

🚀 Get started

This package is published on NPM.

npm install markdown-macros

🛠️ Usage

In the following examples, we will use the buildMacros, parse and execMacros functions.

Say we have this markdown content:

# My document

Say "@MACRO:HELLO()" in a paragraph!

Learn more about [Darth Vader](@MACRO:WIKI_URL('Darth_Vader')).

First, we have to define our macros. A macro definition is an object with a exec function that takes any JSON compatible arguments.

Note that macro names will be normalized (transformed to CONSTANT_CASE). See isValidMacroName function.

Also, note that if you pass unknown identifiers to a macro expression, it will throw a parsing error:

// @MACRO:EXAMPLE('foo', { "bar": baz })
// ❌ Unable to parse Identifier: "baz"

const macroDefinitions = {
  hello: {
    exec: () => 'Hello!'
  },
  wikiUrl: {
    exec: (value: string) => `https://en.wikipedia.org/wiki/${value}`
  }
}

Then, use the buildMacros and execMacros to perform replacements:

import { buildMacros, execMacros } from 'markdown-macros'

const macros = buildMacros(macroDefinitions)

const result = execMacros(macros, content)

console.log(result)

The result will be:

# My document

Say "Hello!" in a paragraph!

Learn more about [Darth Vader](https://en.wikipedia.org/wiki/Darth_Vader).

You can also use the parse function to extract the macro expressions:

import { parse } from 'markdown-macros'

const macroExpressions = parse(content)

The result is an array of parsed macro expressions:

[
  {
    expression: '@MACRO:HELLO()',
    name: 'HELLO',
    args: [],
    rawArgs: '',
    index: 20,
    regExp: RegExp
  },
  {
    expression: "@MACRO:WIKI_URL('Darth_Vader')",
    name: 'WIKI_URL',
    args: [ 'Darth_Vader' ],
    rawArgs: "'Darth_Vader'",
    index: 84,
    regExp: RegExp
  }
]

💡 Please check the API documentation.

Now, let's try the remark, markdown-it, and marked plugins.

remark

import { remark } from 'remark'
import remarkPlugin from 'markdown-macros/remark'

const processor = remark()
  .use(remarkPlugin, {
    hello: {
      exec: () => 'Hello!'
    }
  })

const result = String(await processor.process('# @MACRO:HELLO()'))
// # Hello!

👀 See also remarkPlugin

markdown-it

import MarkdownIt from 'markdown-it'
import markdownItPlugin from 'markdown-macros/markdown-it'

const md = new MarkdownIt()

md.use(markdownItPlugin, {
  hello: {
    exec: () => 'Hello!'
  }
})

md.render('# @MACRO:HELLO()')
// <h1>Hello!</h1>

👀 See also markdownItPlugin

marked

import { Marked } from 'marked'
import markedPlugin from 'markdown-macros/marked'

const marked = new Marked()

marked.use(markedPlugin({
  hello: {
    exec: () => 'Hello!'
  }
}))

marked.parse('# @MACRO:HELLO()')
// <h1>Hello!</h1>

👀 See also markedPlugin

🤝 Contribute

You would like to contribute to this project? You are welcome!

First, please check:

• the contribution guide
• the code of conduct

👑 Author

Made with ❤ by Hervé Perchec

⚖️ License

MIT

📰 Changelog

See all changes to this project in the CHANGELOG.md file.

README.md - this file was auto generated with juisy README templater. Don't edit it.