Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bradlc/mdx-annotations
Markdoc-style annotations for MDX
https://github.com/bradlc/mdx-annotations
markdoc markdown mdx recma rehype remark
Last synced: about 1 month ago
JSON representation
Markdoc-style annotations for MDX
- Host: GitHub
- URL: https://github.com/bradlc/mdx-annotations
- Owner: bradlc
- License: mit
- Created: 2022-11-30T10:28:08.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2023-11-12T23:01:34.000Z (about 1 year ago)
- Last Synced: 2024-11-01T20:12:15.855Z (about 2 months ago)
- Topics: markdoc, markdown, mdx, recma, rehype, remark
- Language: JavaScript
- Homepage:
- Size: 179 KB
- Stars: 20
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# mdx-annotations
> [Markdoc](https://markdoc.dev/)-style annotations for [MDX](https://mdxjs.com/)
## 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' }}
### Hello, world! {{ id: 'intro' }}
#### 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' }}
{{ className: 'object-cover' }}
```