bradlc / mdx-annotations

Markdoc-style annotations for MDX

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

mdx-annotations's Issues

vite + vuejs annotation prop

Hi,

I'm experiencing some issues with mdx-annotation in a Vite + Vue.js project.

Sandbox : https://stackblitz.com/edit/vitejs-vite-syte2b

<h1 annotation="{ id: 'foo' }">Foo</h1>

Expected result:

<h1 id="foo">Foo</h1>

Am I missing something?

Thanks !

Rebuilding Protocol lockfile results in annotations

Sorry that this is specific to the Protocol template, however it's the only use case I have for this issue.

Essentially what's happening is that with a fresh download of the Protocol template, the specific deps listed in the lockfile work perfectly. However, if the lockfile is rebuilt (or you switch to a different package manager), there's an issue with mdx-annotations where it can successfully identify annotations and apply the annotation prop, but it's can't replace them with actual properties later on.

I went into a messy deep dive on Twitter. Seeing as it's dependency version based, I'm guessing it's based on an upgrade to an underlying dependency not directly listed. The diff o the thread might help. In terms of actually fixing it, I think the answer might lie in the recma transformer. Happy to do more digging if it helps. I'd be curious to see what the answer is!

✌️