remark-directive-sugar

A remark plugin provides predefined directives for customizable badges, links, video embeds, enhanced image formatting, and more.

What is this?

This plugin is built on top of remark-directive, supporting regular usage and providing the following predefined directives:

• :badge[-*]: Generates customizable badges.
• :link: Creates links to GitHub, npm, or custom URLs.
• ::video[-*]: Embeds videos from platforms like YouTube, Bilibili, Vimeo, or custom sources.
• :::image-*: Wraps an image inside valid HTML tags, such as a <figure> element to allow adding a descriptive <figcaption>, or a hyperlink to make it clickable, and more.

When should I use this?

If you're using remark-directive, this plugin provides ready-to-use directives, saving you from writing custom code. If you're building a blog with frameworks like Astro or Next.js, it helps enhance your Markdown / MDX content without repetitive HTML.

[!NOTE]
This plugin requires remark-directive, so make sure to install it as well. Check out the Remark Directive Syntax for a quick and easy overview!

Installation

This package is ESM only. In Node.js (version 16+), install with your package manager:

1npm install remark-directive-sugar
2yarn add remark-directive-sugar
3pnpm add remark-directive-sugar

In Deno with esm.sh:

1import remarkDirectiveSugar from 'https://esm.sh/remark-directive-sugar'

In browsers with esm.sh:

1<script type="module">
2  import remarkDirectiveSugar from 'https://esm.sh/remark-directive-sugar?bundle'
3</script>

Usage

Import and configure the plugin based on your target environment.

For vanilla JS：

1// example.js
2import { unified } from 'unified'
3import remarkParse from 'remark-parse'
4import remarkDirective from 'remark-directive'
5import remarkDirectiveSugar from 'remark-directive-sugar'
6import remarkRehype from 'remark-rehype'
7import rehypeStringify from 'rehype-stringify'
8import { readSync } from 'to-vfile'
9
10const file = unified()
11  .use(remarkParse)
12  .use(remarkDirective)
13  .use(remarkDirectiveSugar)
14  .use(remarkRehype)
15  .use(rehypeStringify)
16  .processSync(readSync('example.md'))
17
18console.log(String(file))

For Astro projects:

1// astro.config.ts
2import { defineConfig } from 'astro/config'
3import remarkDirective from 'remark-directive'
4import remarkDirectiveSugar from 'remark-directive-sugar'
5
6// https://docs.astro.build/en/reference/configuration-reference/
7export default defineConfig({
8  markdown: {
9    remarkPlugins: [remarkDirective, remarkDirectiveSugar],
10  },
11})

For Next.js projects:

1// next.config.ts
2import createMDX from '@next/mdx'
3import remarkDirective from 'remark-directive'
4import remarkDirectiveSugar from 'remark-directive-sugar'
5import type { NextConfig } from 'next'
6
7// https://nextjs.org/docs/app/api-reference/config/next-config-js
8const nextConfig: NextConfig = {
9  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
10}
11
12const withMDX = createMDX({
13  options: {
14    remarkPlugins: [remarkDirective, remarkDirectiveSugar],
15    // With Turbopack, specify plugin names as strings
16    // remarkPlugins: [['remark-directive'],['remark-directive-sugar']],
17  },
18})
19
20export default withMDX(nextConfig)

All predefined directives generate only the HTML structure, allowing you to style them with class names or attributes.

:badge[-*]

Use :badge[-*] directive to display small pieces of information, such as status or category. Say example.md contains:

1<!-- Direct usage with text in `[]` -->
2
3Example 1: :badge[New]
4Example 2: :badge[Success]{style="color: black; background-color: #aaf233"}
5
6<!-- Using presets: `presets: {a: { text: 'ARTICLE' }, v: { text: 'VIDEO', props: { className: ['custom'] } }}` -->
7
8Example 3: :badge-a
9Example 4: :badge-v

Run node example.js (pnpm dev) to get:

1<p>
2  Example 1: <span class="rds-badge">New</span>
3  Example 2: <span style="color: black; background-color: #aaf233" class="rds-badge">Success</span>
4</p>
5<p>
6  Example 3: <span data-badge="a" class="rds-badge">ARTICLE</span>
7  Example 4: <span data-badge="v" class="rds-badge custom">VIDEO</span>
8</p>

:link

Use :link directive to create links with avatars or favicons for GitHub, npm, or custom URLs. Say example.md contains:

1<!-- Link to a GitHub user or organization (prepend `id` or `#` with `@`) -->
2<!-- Use `tab` to navigate sections: -->
3<!-- for users: 'repositories', 'projects', 'packages', 'stars', 'sponsoring', 'sponsors' -->
4<!-- for orgs: 'org-repositories', 'org-projects', 'org-packages', 'org-sponsoring', 'org-people' -->
5
6Example 1: :link{#@lin-stephanie}
7Example 2: :link{#@lin-stephanie tab=repositories}
8Example 3: :link[Vite]{id=@vitejs}
9Example 4: :link[Vite]{id=@vitejs tab=org-people}
10
11<!-- Link to a GitHub repository -->
12
13Example 5: :link{#lin-stephanie/remark-directive-sugar}
14Example 6: :link[Astro]{id=withastro/astro}
15
16<!-- Link to an npm package -->
17<!-- Use `tab` to navigate sections: 'readme', 'code', 'dependencies', 'dependents', 'versions' -->
18
19Example 7: :link{#remark-directive-sugar}
20Example 8: :link{id=remark-directive-sugar tab=dependencies}
21
22<!-- Link to a custom URL (must use `id`, not `#`) -->
23
24Example 9: :link{id=https://developer.mozilla.org/en-US/docs/Web/JavaScript}
25Example 10: :link[Google]{id=https://www.google.com/}
26
27<!-- Use `url` to override the default link -->
28<!-- Use `img` to set a custom display image -->
29
30Example 11: :link[Vite]{id=@vitejs url=https://vite.dev/}
31Example 12: :link[Vite]{id=@vitejs img=https://vitejs.dev/logo.svg}

Run node example.js (pnpm dev) to get:

1<p>
2  Example 1:
3  <a href="https://github.com/lin-stephanie" data-link="github-acct" class="rds-link">
4    <img src="https://github.com/lin-stephanie.png" alt="" />
5    lin-stephanie
6  </a>
7  Example 2:
8  <a href="https://github.com/lin-stephanie?tab=repositories" data-link="github-acct" class="rds-link">
9    <img src="https://github.com/lin-stephanie.png" alt="" />
10    lin-stephanie
11  </a>
12  Example 3:
13  <a href="https://github.com/vitejs" data-link="github-acct" class="rds-link">
14    <img src="https://github.com/vitejs.png" alt="" />
15    Vite
16  </a>
17  Example 4:
18  <a href="https://github.com/orgs/vitejs/people" data-link="github-acct" class="rds-link">
19    <img src="https://github.com/vitejs.png" alt="" />
20    Vite
21  </a>
22</p>
23
24<p>
25  Example 5:
26  <a href="https://github.com/lin-stephanie/remark-directive-sugar" data-link="github-repo" class="rds-link">
27    <img src="https://github.com/lin-stephanie.png" alt=""/>
28    lin-stephanie/remark-directive-sugar
29  </a>
30  Example 6:
31  <a href="https://github.com/withastro/astro" data-link="github-repo" class="rds-link">
32    <img src="https://github.com/withastro.png" alt="" />
33    Astro
34  </a>
35</p>
36
37<p>
38  Example 7:
39  <a href="https://www.npmjs.com/package/remark-directive-sugar" data-link="npm-pkg" class="rds-link">
40    <img src="https://api.faviconkit.com/www.npmjs.com" alt="">
41    remark-directive-sugar
42  </a>
43  Example 8:
44  <a href="https://www.npmjs.com/package/remark-directive-sugar?activeTab=dependencies" data-link="npm-pkg" class="rds-link">
45    <img src="https://api.faviconkit.com/www.npmjs.com" alt="">
46    remark-directive-sugar
47  </a>
48</p>
49
50<p>
51  Example 9:
52  <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript" data-link="custom-url" class="rds-link">
53    <img src="https://api.faviconkit.com/developer.mozilla.org" alt="">
54    developer.mozilla.org/en-US/docs/Web...
55  </a>
56  Example 10:
57  <a href="https://www.google.com/" data-link="custom-url" class="rds-link">
58    <img src="https://api.faviconkit.com/www.google.com" alt="">
59    Google
60  </a>
61</p>
62
63<p>
64  Example 11:
65  <a href="https://vite.dev/" data-link="github-acct" class="rds-link">
66    <img src="https://github.com/vitejs.png" alt="">
67    Vite
68  </a>
69  Example 12:
70  <a href="https://github.com/vitejs" data-link="github-acct" class="rds-link">
71    <img src="https://vitejs.dev/logo.svg" alt="">
72    Vite
73  </a>
74</p>

::video[-*]

Use ::video[-*] for consistent video embedding across different platforms. Say example.md contains:

1<!-- Embed a YouTube video -->
2
3::video-youtube{#gxBkghlglTg}
4
5<!-- Embed a Bilibili video -->
6
7::video-bilibili{id=BV1MC4y1c7Kv}
8
9<!-- Embed a Vimeo video with a custom `title` attr -->
10
11::video-vimeo[custom title]{id=912831806}
12
13<!-- Embed a custom video URL (must use `id`, not `#`) -->
14
15::video{id=https://www.youtube-nocookie.com/embed/gxBkghlglTg}

Run node example.js (pnpm dev) to get:

1<iframe
2  src="https://www.youtube-nocookie.com/embed/gxBkghlglTg"
3  title="Video Player"
4  data-video="youtube"
5  class="rds-video"
6></iframe>
7
8<iframe
9  src="https://player.bilibili.com/player.html?bvid=BV1MC4y1c7Kv"
10  title="Video Player"
11  data-video="bilibili"
12  class="rds-video"
13></iframe>
14
15<iframe
16  src="https://player.vimeo.com/video/912831806"
17  title="custom title"
18  data-video="vimeo"
19  class="rds-video"
20></iframe>
21
22<iframe
23  src="https://www.youtube-nocookie.com/embed/gxBkghlglTg"
24  title="Video Player"
25  data-video="url"
26  class="rds-video"
27></iframe>

:::image-*

Use :::image-* to wrap images in a container for captions, clickable links, and more (* must be a valid HTML tag). Say example.md contains:

1<!-- `:::image-figure[caption]{<figcaption> attrs}` -->
2<!-- `[]` hold the figcaption，if not set, the alt text from `![]()` will be used as the default -->
3
4:::image-figure[Figcaption text]
5![Alt text](https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg)
6:::
7
8:::image-figure{style="text-align:center; color:orange"}
9![Text for both alt and figcaption](https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg)
10:::
11
12<!-- `:::image-a{<a> attrs}` -->
13
14:::image-a{href="https://github.com/lin-stephanie/remark-directive-sugar"}
15![](https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg)
16:::
17
18<!-- `:::image-*{<*> attrs}` -->
19
20:::image-div
21![](https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg)
22:::
23
24<!-- Setting `stripParagraph: false` keeps `<p>` to prevent parsing issues with other remark plugins like `remark-imgattr` -->
25
26:::image-figure[Figcaption text]
27![Alt text](https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg)
28:::
29
30:::image-a{href="https://github.com/lin-stephanie/remark-directive-sugar"}
31![](https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg)
32:::

Run node example.js (pnpm dev) to get:

1<figure>
2  <img src="https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg" alt="Alt text">
3  <figcaption>Figcaption text</figcaption>
4</figure>
5
6<figure>
7  <img src="https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg" alt="Text for both alt and figcaption">
8  <figcaption style="text-align:center; color:orange">Text for both alt and figcaption</figcaption>
9</figure>
10
11<a href="https://github.com/lin-stephanie/remark-directive-sugar">
12  <img src="https://images.pexels.com/photos/237272/pexels-photo-237273.jpeg" alt="">
13</a>
14
15<div>
16  <img src="https://images.pexels.com/photos/237272/pexels-photo-237273.jpeg" alt="">
17</div>
18
19<figure>
20  <p>
21    <img src="https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg" alt="Alt text">
22  </p>
23  <figcaption>Figcaption text</figcaption>
24</figure>
25
26<a href="https://github.com/lin-stephanie/remark-directive-sugar">
27  <p>
28    <img src="https://images.pexels.com/photos/237273/pexels-photo-237273.jpeg" alt="">
29  </p>
30</a>

API

This package exports no identifiers. The default export is remarkDirectiveSugar.

unified().use(remarkDirectiveSugar[, options])

Used to provid predefined directives.

Parameters

• options (Options, optional) — configuration

Returns

Transform (Transformer).

Options

Configuration (TypeScript type). All options are optional.

Fields

• badge (BadgeDirectiveConfig) — :badge[-*] configuration options.
• link (LinkDirectiveConfig) — :link configuration options.
• video (VideoDirectiveConfig) — ::video[-*] configuration options.
• image (ImageDirectiveConfig) — :::image-* configuration options.

Types

This package is fully typed with TypeScript. It exports the additional types Options, BadgeDirectiveConfig, LinkDirectiveConfig, VideoDirectiveConfig, ImageDirectiveConfig, PropertiesFromContainerDirective, PropertiesFromLeafDirective and PropertiesFromTextDirective. See jsDocs.io for type details.

Contribution

If you see any errors or room for improvement on this plugin, feel free to open an issues or pull request . Thank you in advance for contributing!

License

MIT © 2024-PRESENT Stephanie Lin