marked-directive

A marked extension to support directives syntax.

Install

You can install marked-directive using npm or yarn:

``bash
npm i marked-directive


or


yarn add marked-directive
`

Usage


Say we have the following file example.md:

`md


Example

:::main{#foo .bar class="baz" .qux}

Directives syntax

::hr{.border-muted}

You can use :i[CSS] (Cascading Style Sheets) to style your :abbr[HTML]{title="HyperText Markup Language"}.

:::
`

And our module example.js looks as follows:

`js
import { readFileSync } from 'node:fs'
import { Marked } from 'marked'
import { createDirectives } from 'marked-directive'

const html = new Marked()
.use(createDirectives())
.parse(readFileSync('example.md', 'utf8'))

console.log(html)
`

Now, running node example.js yields:

`html


Example

href="https://talk.commonmark.org/t/generic-directives-plugins-syntax/444"
>Directives syntax >

---

You can use CSS (Cascading Style Sheets) to style your
HTML.

`

Custom Directives

The marked-directive extension accepts a set of custom configurations for your directives. You can specify how the directives are identified, how they should be rendered, and other behavior. The options include:

- level: The level of the directive, which can be 'container', 'block', or 'inline'. This determines where the directive can be used.
- marker: The marker string that identifies the directive in the source text.
- tag: An optional HTML tag that the directive should be rendered as. If not provided, the default tag is used based on the directive level.
- renderer: A custom rendering function for the directive. This function can be used to customize how the directive is rendered.

Here's an example of custom options:

Say we have the following markdown code:

`md
Custom directives:

::youtube[Dummy video]{vid="9xwazD5SyVg"}

1. @bent10
2. #markdown
3. :emoji[rocket]{title="Go!"}

And whatever is on your mind 🤯.
`

`ts
import { Marked } from 'marked'
import {
createDirectives,
presetDirectiveConfigs,
type DirectiveConfig
} from 'marked-directive'

// defines :youtube directive
const youtubeDirective: DirectiveConfig = {
level: 'block',
marker: '::',
renderer(token) {
if (token.meta.name === 'youtube') {
return
}

return false
}
}

// defines @mention directive
const mentionDirective: DirectiveConfig = {
level: 'inline',
marker: '@',
renderer(token) {
return ${token.meta.name}
}
}

// defines #hashtag directive
const hashtagDirective: DirectiveConfig = {
level: 'inline',
marker: '#',
renderer(token) {
return ${token.meta.name}
}
}

// defines :emoji directive
const emojis = { rocket: '🚀', 'red-exclamation': '❗' } // mock emoji api
const emojiDirective: DirectiveConfig = {
level: 'inline',
marker: ':',
renderer(token) {
if (token.meta.name === 'emoji') {
return ${emojis[token.text]}
}

return false
}
}

const html = new Marked()
.use(
createDirectives([
...presetDirectiveConfigs,
youtubeDirective,
mentionDirective,
hashtagDirective,
emojiDirective
])
)
.parse(md)

console.log(html)
`

![Try marked-directive on RunKit](https://untitled-owlc7cxj7jxp.runkit.sh/)

Nested Directives

When working with nested directives, it’s important to ensure proper distinction between different levels of nesting. If both the container and its nested items use the same marker character (e.g., :), the number of marker characters should increment with each level of nesting to avoid conflicts and ensure correct parsing.

For example, in the following Markdown snippet, the .container uses four colons (::::) to define its boundaries, while the nested .item uses three colons (:::):

`md
::::{.container}

:::{.item}
Title
Description

!Image
:::

::::
`

Alternatively, you can also use different markers for each level. For example, the .container uses colons (:::), and the .item uses plus signs (+++):

``md
:::{.container}

+++{.item}

$3

Content !Image, with code:

`python
num1 = 5
num2 = 3
sum = num1 + num2
print(f"The sum of {num1} and {num2} is {sum}")
`

+++

:::
``

To handle these custom markers, set up the directives like this:

`js
import { Marked } from 'marked'
import { createDirectives, presetDirectiveConfigs } from 'marked-directive'

const md = // markdown above
const html = new Marked()
.use(
createDirectives([
...presetDirectiveConfigs,
// custom directives
{ level: 'container', marker: '::::' },
{ level: 'container', marker: '\\+\\+\\+' }
])
)
.parse(md)

console.log(html)
`

Related

See extensions list.

Contributing

We 💛  issues.

When committing, please conform to the semantic-release commit standards. Please install commitizen and the adapter globally, if you have not already.

`bash
npm i -g commitizen cz-conventional-changelog
`

Now you can use git cz or just cz instead of git commit when committing. You can also use git-cz, which is an alias for cz.

`bash
git add . && git cz
``

License

!GitHub

A project by Stilearning © 2023-2024.