remark-merge-data

A remark plugin that makes it possible to share global configuration for code blocks in markdown that contain either JSON or YAML data (or any other format if you provide your own parse and stringify), like when e.g. using kroki.

Generic example

Assuming example.md contains the following:

```some-language
{
  "localProp": 0
}
```
```some-language
{
  "localProp": 1
}
```
```some-other-language
{
  "localProp": 2
}
```

import readFileSync from 'node:fs';
import { remark } from 'remark';
import { MergeDataOptions, remarkMergeData } from "remark-merge-data";

const mergeDataOptions: MergeDataOptions[] = [{
  lang: "some-language",
  data: {
    globalProp: 3,
  },
}, {
  lang: "some-other-language",
  data: {
    globalProp: 4,
  },
}];

remark()
  .use(remarkMergeData, mergeDataOptions)
  .process(readFileSync('example.md', 'utf8'))
  .then(({value}) => console.log(value))
  .catch((error) => console.error(error));

Will log:

```some-language
{
  "globalProp": 3,
  "localProp": 0
}
```
```some-language
{
  "globalProp": 3,
  "localProp": 1
}
```
```some-other-language
{
  "globalProp": 4,
  "localProp": 2
}
```

Practical example

See this article for an example where graphs are defined in code blocks. To avoid large amounts of duplicate definitions, everything that can be shared is merged with the data in those code blocks using this plugin.

API

export type MergeDataOptions = (
  | {
      /**
       * The data that will be merged with the data in the selected code blocks.
       * This is the "base" data. The data in every code block can overwrite the global data specified here.
       */
      data: unknown;

      isYaml?: false;
    }
  | {
      data: string;

      isYaml?: true;
    }
) & {
  /** The language of the code blocks that should be processed. For more specific filtering, use `meta` in addition. */
  lang: string;

  /** By default, lodash's merge is used. */
  merge?: (target: unknown, source: unknown) => unknown;
  /**
   * This can be used to filter by arbitrary metadata key-value pairs.
   * Looks e.g. like this in markdown: ```kroki type=vegalite orientation=horizontal
   * Note: The whole metadata object has to match!
   */
  meta?: Record<string, string>;
  /** By default, `JSON.parse` is used. (`yaml.parse` if YAML is used.) */
  parse?: (data: string) => unknown;
  /** By default, `JSON.stringify` is used. (`yaml.stringify` if YAML is used.) */
  stringify?: (data: unknown) => string;
};

Thanks

• @jordemort - for illustrating how easy customizing things in blogs with remark can be.
• @remcohaszing - for inspiring me to publish this plugin and how to structure it. (See his mermaid plugin)