# remark-custom-blocks

> This plugin parses custom Markdown syntax to create new custom blocks. It adds new nodes types to the [mdast][mdast] produced by [remark][remark]:

Latest version **2.6.1** (published 2024-04-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install remark-custom-blocks
pnpm add remark-custom-blocks
yarn add remark-custom-blocks
bun add remark-custom-blocks
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: no vulnerabilities; high maintenance score.

Warnings: low downloads; no types; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 2.6.1 |
| Published | 2024-04-27 |
| First published | 2017-06-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 17.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 237 |
| Author | Victor Felder |
| Maintainers | situphen, talone |
| Keywords | remark |

## Links

- npm: https://www.npmjs.com/package/remark-custom-blocks
- Repository: https://github.com/zestedesavoir/zmarkdown.git#master
- Homepage: https://github.com/zestedesavoir/zmarkdown/tree/master#readme
- Issues: https://github.com/zestedesavoir/zmarkdown/issues
- npm.io page: https://npm.io/package/remark-custom-blocks

## Dependencies (1)

- [space-separated-tokens](https://npm.io/package/space-separated-tokens.md) ^1.1.5

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 2.6.1 (latest) — 2024-04-27
- 2.6.0 — 2022-03-29
- 2.5.1 — 2021-02-14
- 2.5.0 — 2020-03-06
- 2.4.6 — 2020-02-03
- 2.4.5 — 2020-01-21
- 2.4.2 — 2019-08-29
- 2.4.1 — 2019-07-27
- 2.4.0 — 2019-07-12
- 2.3.3 — 2019-04-14
- 2.3.2 — 2019-02-04
- 2.3.1 — 2018-11-23
- 2.3.0 — 2018-10-04
- 2.2.3 — 2018-08-09
- 2.2.2 — 2018-07-22
- … 30 more at https://npm.io/package/remark-custom-blocks/versions

## README

# remark-custom-blocks [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status]

This plugin parses custom Markdown syntax to create new custom blocks.
It adds new nodes types to the [mdast][mdast] produced by [remark][remark]:

* `{yourType}CustomBlock`

If you are using [rehype][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](http://docdock.netlify.com/shortcodes/panel/).

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][mdast] specification)

By default, the plugin will produce the following two nodes, where `whatnot` is the name of you block:

```javascript
interface whatnotCustomBlock <: Parent {
  type: "whatnotCustomBlock";
  data: {
    hName: "div" or "details";
    hProperties: {
      className: [string];
    }
  }
}
```

```javascript
interface whatnotCustomBlockBody <: Parent {
  type: "whatnotCustomBlockBody";
  data: {
    hName: "div";
    hProperties: {
      className: [string];
    }
  }
}
```

If your block has a heading, the following node will also be produced:

```javascript
interface whatnotCustomBlockHeading <: Parent {
  type: "whatnotCustomBlockHeading";
  data: {
    hName: "div" or "summary";
    hProperties: {
      className: [string];
    }
  }
}
```

## Installation

[npm][npm]:

```bash
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

```html
<containerElement>
    <titleElement>
        block title
    </titleElement>
    <contentsElement>
        block content
    </contentsElement>
</containerElement>
```

you can see `details: true` as a shortcut to

```javascript
{
    containerElement: 'details',
    titleElement: 'summary',
    contentsElement: 'div',
}
```

Those specific parameters are here to help you build semantic HTML structure.

#### Dependencies:

```javascript
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:

```javascript
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:

    ```markdown
    [[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.

1. This Remark plugin would create [mdast][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`

1. If you're using [rehype][rehype], you will end up with these 4 `div`s and 1 `details`:

    ```html
    <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][license] © [Zeste de Savoir][zds]

<!-- Definitions -->

[build-badge]: https://img.shields.io/travis/zestedesavoir/zmarkdown.svg

[build-status]: https://travis-ci.org/zestedesavoir/zmarkdown

[coverage-badge]: https://img.shields.io/coveralls/zestedesavoir/zmarkdown.svg

[coverage-status]: https://coveralls.io/github/zestedesavoir/zmarkdown

[license]: https://github.com/zestedesavoir/zmarkdown/blob/master/packages/remark-custom-blocks/LICENSE-MIT

[zds]: https://zestedesavoir.com

[npm]: https://www.npmjs.com/package/remark-custom-blocks

[mdast]: https://github.com/syntax-tree/mdast/blob/master/readme.md

[remark]: https://github.com/remarkjs/remark

[rehype]: https://github.com/rehypejs/rehype

---
_Source: https://npm.io/package/remark-custom-blocks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._