mdx-annotations

Markdoc-style annotations for MDX

Installation

npm install mdx-annotations

To maximise compatibility mdx-annotations is provided as three separate plugins that must be used together:

import { compile } from '@mdx-js/mdx'
import { mdxAnnotations } from 'mdx-annotations'

let mdx = `# Hello, world! {{ id: 'intro' }}`

await compile(mdx, {
  remarkPlugins: [mdxAnnotations.remark],
  rehypePlugins: [mdxAnnotations.rehype],
  recmaPlugins: [mdxAnnotations.recma],
})

Note
It is recommended to include each plugin first in their respective plugin arrays.

Usage

An annotation is a JavaScript object associated with an MDX node. The object properties are passed to the resulting JSX element as props.

Input:

# Hello, world! {{ id: 'intro' }}

Output:

<h1 id="intro">Hello, world!</h1>

Examples

Headings

# Hello, world! {{ id: 'intro' }}

## Hello, world! {{ id: 'intro' }}

### Hello, world! {{ id: 'intro' }}

#### Hello, world! {{ id: 'intro' }}

List items

- Hello, world! {{ id: 'intro' }}

When a list item contains multiple children the annotation is attached to the child:

Input:

- Hello, world! {{ className: 'text-lg' }}

  Lorem ipsum {{ className: 'text-sm' }}

Output:

<ul>
  <li>
    <p className="text-lg">Hello, world!</p>
    <p className="text-sm">Lorem ipsum</p>
  </li>
</ul>

Code

```{{ title: 'Example' }}
Hello, world!
```

```php {{ title: 'Example' }}
echo 'Hello, world!';
```

Thematic breaks

--- {{ className: 'my-10' }}

*** {{ className: 'my-10' }}

Inline elements

To annotate an inline element ensure that there is no whitespace between the element and the annotation:

**Hello world**{{ className: 'text-red-500' }}
_Hello world_{{ className: 'text-red-500' }}
`Hello world`{{ className: 'text-red-500' }}
[Hello world](#){{ className: 'text-red-500' }}
![](/img.png){{ className: 'object-cover' }}