r e h y p e - f n - c i t a t i o n - s p a c e r

A rehype plugin that makes some space between adjacent in-text footnote citations/references.

Summary

This is a simple rehype plugin that's designed to run after remark-gfm, and separates any generated in-text footnote citations/references found in the hast tree with either a comma and a space (default) or a user defined spacer.

Summary
Table of Contents
The Problem
This Solution: Plugin Named rehype-fn-citation-spacer
- Other Solutions I Explored
Install
Usage
Contributing
- Reporting Bugs
- Suggesting New Features

The Problem

Figure 1: Using pure Github Flavored Markdown syntax, serial In-text footnote citations 1, 2, 3, & 4 get squished in the resultant markup, appearing as 1234 instead.

Github Flavored Markdown allows you to create footnotes and in-text footnote citations/references like this:

My cool statement[^reference-1], which is supported by other cool statements[^reference-2][^reference-3].

[^reference-1]: Doe, Jane. 2025. Cool Paper Title.
[^reference-2]: Doe, John. 2024. Supporting Paper Title.
[^reference-3]: Doe, Jane. 2023. Other Supporting Paper Title.

The only problem is that when multiple inline references are used in serial they wind up squished together, making for a pretty confusing user experience. The above example would look like 2 3 instead of 2 3, similar to Figure 1. That's because in the HTML, the footnote citations are literally stuck together.

<p>
  "My cool statement"
  <sup><a>1</a></sup>
  ", which is supported by other cool statements"
  <sup><a>2</a></sup>
  <sup><a>3</a></sup>
  "."
</p>

This Solution: Plugin Named rehype-fn-citation-spacer

Figure 2: Using rehype-fn-citation-spacer with its default configuration, serial In-text footnote citations 1, 2, 3, & 4 appear properly as 1, 2, 3, 4.

The core of the problem was a lack of space between in-text footnote references. So, I wrote this rehype plugin to inject a spacer (default: , ) between adjacent  nodes in the hast tree, to make some space.

Specifically, the spacer is injected between sequential  nodes containing a single child <a /> node with an arbitrary target data-attribute (default: data-footnote-ref). The end result of this process is demonstrated by Figure 2.

Likewise, using Figure 2 as a basis, we can estimate that the resultant post-injection HTML of the initial example would probably look something like this:

<p>
  "My cool statement"
  <sup><a>1</a></sup>
  ", which is supported by other cool statements"
  <sup><a>2</a></sup>
  <sup>, </sup>
  <sup><a>3</a></sup>
  "."
</p>

Install

This is a ESM only module.

You can install rehype-fn-citation-spacer with any node package manager. Using bun as an example, the command looks like:

bun add rehype-fn-citation-spacer

why remark-gfm isn't a dependency.

rehype-fn-citation-spacer won't error out if it's not present. In fact, so long as it finds  nodes, that wrap a single element node with some target data-attribute (see: fnDataAttr), it will inject a spacer just fine.

Usage

Default (Empty Configuration)

For the default behavior (spacer: , , fnDataAttr: "dataFootnoteRef"), simply import and load rehypeFnCitationSpacer into your rehype plugins array. No configuration needed.

import {compile} from '@mdx-js/mdx';
import remarkGfm from 'remark-gfm';
import rehypeFnCitationSpacer from 'rehype-fn-citation-spacer'

const processed = await compile("# Some Markdown File", {
  remarkPlugins: [remarkGfm],
  rehypePlugins: [rehypeFnCitationSpacer]
});

Custom Spacer

If you want a different spacer, this plugin let's you do it! Just define a custom spacer, and load it into the rehypeFnCitationSpacer configuration object.

Important: Your spacer needs to be of type ElementContent, otherwise it will fail to inject! You should also enable verboseErr to get detailed error messages from the plugin.

import {compile} from '@mdx-js/mdx';
import remarkGfm from 'remark-gfm';
import rehypeFnCitationSpacer, {type rehypeFnCitationSpacerConfig} from 'rehype-fn-citation-spacer'

const myCustomRFCSConfig = {
  spacer: {
    type: 'element',
    tagName: 'sup',
    properties: {},
    children: [
      {
        type: 'text',
        value: ' | ',
      },
    ],
  },
  verboseErr: false
} satisfies rehypeFnCitationSpacerConfig; // only needed if you want type checking

const processed = await compile("# Some Markdown File", {
  remarkPlugins: [remarkGfm],
  rehypePlugins: [[rehypeFnCitationSpacer, myCustomRFCSConfig]]
});

Configuration Reference

Property	Expected Type	Default Value	Description
spacer	optional `ElementContent`	{ type: 'element', tagName: 'sup', properties: {}, children: [ { type: 'text', value: ', ', }, ], };	If you'd like to use your own spacer, you can define a custom spacer here. It must be of type `ElementContent` from `@types/hast`, otherwise the plugin won't inject it.
fnDataAttr	optional (`string` && `string.length() > 0`)	`"dataFootnoteRef"`	This is a value defined in camelCase. The default is `dataFootnoteRef` which is found on the superscript wrapped anchor elements created by `remarkGfm` (`<a data-footnote-ref="true" ... />`). Unless you've deviated from the default data-attribute `remarkGfm` applies to footnote citation hyperlinks, you don't need to configure this.
verboseErr	optional `boolean`	`false`	This controls the verbosity of the error message printed to the console. By default, it's set to `false`. If you're deviating from the default configuration, you'll probably want to set this to `true`.

Contributing

Contributions are welcome! So, Feel free to submit a PR! Just make sure to include a brief summary of what you've changed/added, and why.

Reporting Bugs

If something's not working right, please don't hesitate to open an issue with the bug label (or other relevant label(s)). Likewise, please make sure to include the following in your bug report:

Describe what happened.
Describe the environment where this occurred (OS, Node.js version, etc.).
The console output generated by using verboseErr: true in your configuration.

Suggesting New Features

If you've got an idea, I'd love to hear about it. Just create a new issue with the enhancement label (or other relevant label(s)).