# remark-captions

> This [remark][remark] plugin adds custom syntax to add a caption to elements which might benefit from a legend. It wraps the said element in a `figure` node with `figcaption` node as last child. It is particularly interesting for use with quotes, images,

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

## Install

```sh
npm install remark-captions
pnpm add remark-captions
yarn add remark-captions
bun add remark-captions
```

## 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.2.4 |
| Published | 2024-04-27 |
| First published | 2017-06-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 21.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 237 |
| Author | François |
| Maintainers | situphen, talone |
| Keywords | remark |

## Links

- npm: https://www.npmjs.com/package/remark-captions
- 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-captions

## Dependencies (3)

- [clone](https://npm.io/package/clone.md) ^2.1.2
- [xtend](https://npm.io/package/xtend.md) ^4.0.2
- [unist-util-visit](https://npm.io/package/unist-util-visit.md) ^2.0.3

## 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.2.4 (latest) — 2024-04-27
- 2.2.3 — 2023-05-05
- 2.2.2 — 2021-06-22
- 2.2.1 — 2021-02-14
- 2.2.0 — 2020-02-03
- 2.1.8 — 2019-07-27
- 2.1.7 — 2019-04-14
- 2.1.6 — 2019-02-04
- 2.1.5 — 2018-11-23
- 2.1.4 — 2018-10-04
- 2.1.3 — 2018-08-31
- 2.1.2 — 2018-08-09
- 2.1.1 — 2018-07-22
- 2.1.0 — 2018-07-20
- 2.0.1 — 2018-03-06
- … 29 more at https://npm.io/package/remark-captions/versions

## README

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

This [remark][remark] plugin adds custom syntax to add a caption to elements which might benefit from a legend. It wraps the said element in a `figure` node with `figcaption` node as last child. It is particularly interesting for use with quotes, images, tables, code blocks.

It follows a "whitelist" approach: for each [mdast][mdast] node type for which you want to allow captioning you'll have to add a configuration property mapping a node type to its caption "trigger".

## Syntax

```markdown
> Do it or do it not, there is no try
Source: A little green man, with a saber larger than himself
```

This takes what follows `Source: ` until the end of the block containing `Source: ` and puts this inside a `figcaption` mdast node. What precedes it becomes children of a `figure` node, the last child of this `figure` node being `figcaption`.

Used with `rehype`, it generates the corresponding HTML elements.

```javascript
interface figure <: Parent {
  type: 'figure'
  data: {
    hName: 'figure',
  }
}
```

```javascript
interface figcaption <: Parent {
  type: 'figcaption'
  data: {
    hName: 'figcaption',
  }
}
```

This plugin handles two different types of caption/legend nodes :

- `internalLegend`: when the caption, after being parsed by `remark`, is inside the captioned element or inside its wrapping paragraph:
   - blockquote
   - image
   - inlineMath
   - iframe
   - ...
- `externalLegend`: when the caption, after being parsed by `remark`, is outside the captioned element or after its wrapping paragraph:
   - table
   - code
   - math
   - ...


## Installation

[npm][npm]:

```bash
npm install remark-captions
```

## Usage

Dependencies:

```javascript
const unified = require('unified')
const remarkParse = require('remark-parse')
const stringify = require('rehype-stringify')
const remark2rehype = require('remark-rehype')

const remarkCaptions = require('remark-captions')
```

Usage:

```javascript
unified()
  .use(remarkParse)
  .use(remarkCaptions, {
    external: {
      table: 'Table:',
      code: 'Code:',
      math: 'Equation:',
    },
    internal: {
      image: 'Figure:',
    }
  })
  .use(remark2rehype)
  .use(stringify)
```

By default, it features :

```javascript
external = {
  table: 'Table:',
  code: 'Code:',
}

internal = {
  blockquote: 'Source:',
  image: 'Figure:',
}
```

## Other examples


This enables you to deal with such a code:

    ```python
    a_highlighted_code('blah')
    ```
    Code: My code *caption*

will yield

```javascript
{
  type: 'figure',
  data: {
    hName: 'figure'
  },
  children: [
    {
      type: 'code',
      language: 'python',
      value: '\na_highlighted_code(\'blah\')\n'
    },
    {
      type: 'figcaption',
      data: {
        hName: 'figcaption'
      }
      children: [
        {
          type: 'text',
          value: 'My code '
        },
        {
          type: 'em',
          children: [
            {
              type: 'text',
              value: 'caption'
            }
          ]
        }
      ]
    }
  ]
}
```

Tables are also supported, example:

```markdown
head1| head2
-----|------
bla|bla
Table: figcapt1
```

Associated with `remark-rehype` this generates a HTML tree encapsulated inside a `<figure>` tag

```html
<figure>
  <table>
    <thead>
      <tr>
        <th>head1</th>
        <th>head2</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>bla</td>
        <td>bla</td>
      </tr>
    </tbody>
  </table>
  <figcaption>figcapt1</figcaption>
</figure>
```

[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-captions/LICENSE-MIT

[zds]: https://zestedesavoir.com

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

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

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

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