the basics

Introduction

remark-notes-plugin turns markdown blockquotes into styled note components.

> [!tip]
> Share best practices and pro tips with your readers.

<blockquote class="remark-note remark-note-tip">
  <div class="remark-note-header">
    <span class="remark-note-icon"><!-- SVG icon --></span>
    <span class="remark-note-title">tip</span>
  </div>
  <div class="remark-note-content">
    <p>Share best practices and pro tips with your readers.</p>
  </div>
</blockquote>

Install

npm install remark-notes-plugin
# or: yarn add remark-notes-plugin
# or: pnpm add remark-notes-plugin

Requires remark v13+ and Node.js v14+.

Usage

Wire the plugin in wherever your project already processes markdown:

Next.js

// next.config.mjs
import createMDX from '@next/mdx';
import remarkNotes from 'remark-notes-plugin';

const withMDX = createMDX({
  options: { remarkPlugins: [remarkNotes] },
});

export default withMDX({
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
});

Astro

// astro.config.mjs
import { defineConfig } from 'astro/config';
import remarkNotes from 'remark-notes-plugin';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkNotes],
  },
});

Gatsby

npm install remark-notes-plugin gatsby-plugin-mdx

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-mdx',
      options: {
        extensions: ['.mdx', '.md'],
        mdxOptions: {
          remarkPlugins: [require('remark-notes-plugin')],
        },
      },
    },
  ],
};

Docusaurus

// docusaurus.config.js
import remarkNotes from 'remark-notes-plugin';

const config = {
  presets: [
    ['classic', {
      docs: { remarkPlugins: [remarkNotes] },
    }],
  ],
};

VitePress

// .vitepress/config.ts
import { defineConfig } from 'vitepress';
import remarkNotes from 'remark-notes-plugin';

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(remarkNotes);
    },
  },
});

VitePress uses markdown-it, not remark, by default — the md.use() call above bridges the two.

Eleventy (11ty)

npm install @11ty/eleventy-plugin-remark remark-notes-plugin

// .eleventy.js
const eleventyRemark = require('@11ty/eleventy-plugin-remark');
const remarkNotes = require('remark-notes-plugin');

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(eleventyRemark, {
    plugins: [remarkNotes],
  });
};

Hugo

Hugo doesn't run remark natively. Preprocess your markdown before Hugo builds:

// scripts/process-markdown.js
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkNotes from 'remark-notes-plugin';
import remarkStringify from 'remark-stringify';
import { readFileSync, writeFileSync } from 'fs';
import { glob } from 'glob';

for (const filepath of glob.sync('content/**/*.md')) {
  const content = readFileSync(filepath, 'utf-8');
  const result = await unified()
    .use(remarkParse)
    .use(remarkNotes, { injectStyles: false })
    .use(remarkStringify)
    .process(content);
  writeFileSync(filepath, result.toString());
}

Vanilla unified/remark

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkNotes from 'remark-notes-plugin';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';

const html = await unified()
  .use(remarkParse)
  .use(remarkNotes)
  .use(remarkRehype, { allowDangerousHtml: true })
  .use(rehypeStringify, { allowDangerousHtml: true })
  .process(markdown);

Styles inject automatically — no CSS import needed. To control that, see Customization.

Every framework here has more detail — alternate routers, extra config options, Hugo's build wiring — on Framework Integration.

The 5 note types

> [!note]
> Perfect for general information and helpful context.

> [!tip]
> Share best practices and pro tips with your readers.

> [!important]
> Highlight critical information that demands attention.

> [!quote]
> Showcase quotes and testimonials beautifully.

> [!bonus]
> Add extra value with advanced techniques.

• note — general information and context
• tip — best practices and suggestions
• important — critical information that demands attention
• quote — quotations and testimonials
• bonus — extra, optional value