marked-directive
A marked extension to support directives syntax.
Install
You can install marked-directive
using npm or yarn:
npm i marked-directive
# or
yarn add marked-directive
Usage
Once you've installed this extension, you can use it in your marked configuration. Here's an example of how to configure it:
Say we have the following file example.md
:
# Example
:::main{#foo .bar class="baz" .qux}
[Directives syntax](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444)
::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:
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:
<h1>Example</h1>
<main id="foo" class="bar baz qux">
<p>
<a
href="https://talk.commonmark.org/t/generic-directives-plugins-syntax/444"
>Directives syntax</a
>
</p>
<hr class="border-muted" />
<p>
You can use <i>CSS</i> (Cascading Style Sheets) to style your
<abbr title="HyperText Markup Language">HTML</abbr>.
</p>
</main>
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:
Custom directives:
::youtube[Dummy video]{vid="9xwazD5SyVg"}
1. @bent10
2. #markdown
3. :emoji[rocket]{title="Go!"}
And whatever is on your mind 🤯.
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 `<iframe width="560" height="315" src="https://www.youtube.com/embed/${
token.attrs?.vid || ''
}" title="${
token.text
}" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>`
}
return false
}
}
// defines `@mention` directive
const mentionDirective: DirectiveConfig = {
level: 'inline',
marker: '@',
renderer(token) {
return `<a class="user-mention notranslate" href="/users/${token.meta.name}">${token.meta.name}</a>`
}
}
// defines `#hashtag` directive
const hashtagDirective: DirectiveConfig = {
level: 'inline',
marker: '#',
renderer(token) {
return `<a class="hashtag" href="/tags/${token.meta.name}">${token.meta.name}</a>`
}
}
// 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 `<span ${token.attrs?.toString()}>${emojis[token.text]}</span>`
}
return false
}
}
const html = new Marked()
.use(
createDirectives([
...presetDirectiveConfigs,
youtubeDirective,
mentionDirective,
hashtagDirective,
emojiDirective
])
)
.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.
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
.
git add . && git cz
License
A project by Stilearning © 2023.