remark-custom-blocks

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 divs 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:

1. 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.

2. This Remark plugin would create mdast nodes for these two blocks, these nodes would be of type:

   • fooCustomBlock, content will be in fooCustomBlockBody
   • barCustomBlock, content in barCustomBlockBody, optional title in barCustomBlockHeading
   • quxCustomBlock, content in quxCustomBlockBody, required title in quxCustomBlockHeading

3. If you're using rehype, you will end up with these 4 divs and 1 details:

   <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

MIT © Zeste de Savoir