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:

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

`markdown


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


`

Output:

`html


Hello, world!


`

Examples

Headings

`markdown


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

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

$3

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

List items

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

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

Input:

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

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

Output:

`html


• 
  

  Hello, world!

  
  

  Lorem ipsum

  
  


`

Code

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

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

Thematic breaks

`markdown
--- {{ 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:

`markdown
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' }}
``