A marked extension to support directives syntax
npm install marked-directiveA marked extension to support directives syntax.
You can install marked-directive using npm or yarn:
``bash`
npm i marked-directiveor
yarn add marked-directive

Say we have the following file example.md:
`mdExample
:::main{#foo .bar class="baz" .qux}
::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.
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${token.meta.name}
const mentionDirective: DirectiveConfig = {
level: 'inline',
marker: '@',
renderer(token) {
return
}
}
// defines #hashtag directive${token.meta.name}
const hashtagDirective: DirectiveConfig = {
level: 'inline',
marker: '#',
renderer(token) {
return
}
}
// defines :emoji directive${emojis[token.text]}
const emojis = { rocket: 'π', 'red-exclamation': 'β' } // mock emoji api
const emojiDirective: DirectiveConfig = {
level: 'inline',
marker: ':',
renderer(token) {
if (token.meta.name === 'emoji') {
return
}
return false
}
}
const html = new Marked()
.use(
createDirectives([
...presetDirectiveConfigs,
youtubeDirective,
mentionDirective,
hashtagDirective,
emojiDirective
])
)
.parse(md)
console.log(html)
`

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}
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)
`
See extensions list.
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
A project by Stilearning © 2023-2024.