remark-custom-blocks v2.6.0
remark-custom-blocks
This plugin parses custom Markdown syntax to create new custom blocks. It adds new nodes types to the mdast produced by remark:
{yourType}CustomBlock
If you are using rehype, the stringified HTML result will be div
s with configurable CSS classes.
It is up to you to have CSS rules producing the desired result for these classes.
The goal is to let you create blocks or panels somewhat similar to these.
Each custom block can specify CSS classes and whether users are allowed or required to add a custom title to the block.
Only inline Markdown will be parsed in titles.
AST nodes (see mdast specification)
By default, the plugin will produce the following two nodes, where whatnot
is the name of you block:
interface whatnotCustomBlock <: Parent {
type: "whatnotCustomBlock";
data: {
hName: "div" or "details";
hProperties: {
className: [string];
}
}
}
interface whatnotCustomBlockBody <: Parent {
type: "whatnotCustomBlockBody";
data: {
hName: "div";
hProperties: {
className: [string];
}
}
}
If your block has a heading, the following node will also be produced:
interface whatnotCustomBlockHeading <: Parent {
type: "whatnotCustomBlockHeading";
data: {
hName: "div" or "summary";
hProperties: {
className: [string];
}
}
}
Installation
npm:
npm install remark-custom-blocks
Usage, Configuration, Syntax
Configuration:
The configuration object follows this pattern:
trigger: {
classes: String, space-separated classes, optional, default: ''
title: String, 'optional' | 'required', optional, default: custom titles not allowed
containerElement: String, optional, default: 'div'
titleElement: String, optional, default: 'div'
contentsElement: String, optional, default: 'div'
details: Boolean, optional, default: false
}
containerElement
, titleElement
, contentsElement
allow you to customize the html elements that will be generated by remark-rehype
stringifier. The generated HTML structure will be
<containerElement>
<titleElement>
block title
</titleElement>
<contentsElement>
block content
</contentsElement>
</containerElement>
you can see details: true
as a shortcut to
{
containerElement: 'details',
titleElement: 'summary',
contentsElement: 'div',
}
Those specific parameters are here to help you build semantic HTML structure.
Dependencies:
const unified = require('unified')
const remarkParse = require('remark-parse')
const stringify = require('rehype-stringify')
const remark2rehype = require('remark-rehype')
const remarkCustomBlocks = require('remark-custom-blocks')
Usage:
unified()
.use(remarkParse)
.use(remarkCustomBlocks, {
foo: {
classes: 'a-class another-class'
},
bar: {
classes: 'something',
title: 'optional'
},
qux: {
classes: 'qux-block',
title: 'required'
},
spoiler: {
classes: 'spoiler-block',
title: 'optional',
details: true
},
})
.use(remark2rehype)
.use(stringify)
The sample configuration provided above would have the following effect:
Allows you to use the following Markdown syntax to create blocks:
[[foo]] | content [[bar]] | content [[bar | my **title**]] | content [[qux | my title]] | content [[spoiler | my title]] | content
- Block
foo
cannot have a title,[[foo | title]]
will not result in a block. - Block
bar
can have a title but does not need to. - Block
qux
requires a title,[[qux]]
will not result in a block.
- Block
This Remark plugin would create mdast nodes for these two blocks, these nodes would be of type:
fooCustomBlock
, content will be infooCustomBlockBody
barCustomBlock
, content inbarCustomBlockBody
, optional title inbarCustomBlockHeading
quxCustomBlock
, content inquxCustomBlockBody
, required title inquxCustomBlockHeading
If you're using rehype, you will end up with these 4
div
s and 1details
:<div class="custom-block a-class another-class"> <div class="custom-block-body"><p>content</p></div> </div> <div class="custom-block something"> <div class="custom-block-body"><p>content</p></div> </div> <div class="custom-block something"> <div class="custom-block-heading">my <strong>title</strong></div> <div class="custom-block-body"><p>content</p></div> </div> <div class="custom-block qux-block"> <div class="custom-block-heading">my title</div> <div class="custom-block-body"><p>content</p></div> </div> <details class="custom-block spoiler-block"> <summary class="custom-block-heading">my title</summary> <div class="custom-block-body"><p>content</p></div> </details>
License
2 years ago
3 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago