Skip to content

README.md

Latest commit

 

History

History
227 lines (162 loc) · 5.11 KB

README.md

File metadata and controls

227 lines (162 loc) · 5.11 KB
Raw

remark-notes-plugin 📝

A powerful TypeScript remark plugin that transforms markdown blockquotes into beautifully styled note elements. Add professional-looking notes, tips, quotes, and more to your markdown documentation with minimal effort!

Test Status npm License Website

✨ Features

  • 🎨 5 Beautiful Note Types - Note, Tip, Important, Quote, and Bonus
  • 🎯 Semantic HTML Output - Clean and accessible HTML structure
  • 💅 Customizable Styling - Easy to override CSS classes
  • 🔧 Easy Integration - Works with any remark-based markdown processor

📦 Installation

npm install remark-notes-plugin

🚀 Usage

Basic Usage

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

const markdown = `
> [!note]
> This is a note about something important.

> [!tip]
> Here's a helpful tip for you.

> [!important]
> This is a very important message!

> [!quote]
> Here's a memorable quote.

> [!bonus]
> Here's some extra content for you!
`

const file = await unified()
  .use(remarkParse)
  .use(remarkNotes)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(markdown)

console.log(String(file))

Configuration Options

import remarkNotes from 'remark-notes-plugin'

// Default configuration (styles are auto-injected)
unified().use(remarkNotes)

// Custom class prefix
unified().use(remarkNotes, { 
  classPrefix: 'my-callout' 
})
// Generates classes like: my-callout-remark-note, my-callout-remark-note-tip, etc.

// Disable automatic style injection (import CSS manually)
unified().use(remarkNotes, { 
  injectStyles: false 
})
// Then import: import 'remark-notes-plugin/styles.css'

// Both options
unified().use(remarkNotes, { 
  classPrefix: 'custom',
  injectStyles: false 
})

📝 Note Types

The plugin supports five distinct types of notes, each with its own unique style:

  1. Note - For general information and remarks

    > [!note]
> Your note content here

  2. Tip - For helpful tips and tricks

    > [!tip]
> Your tip content here

  3. Important - For critical information and warnings

    > [!important]
> Your important message here

  4. Quote - For quotations and references

    > [!quote]
> Your quote content here

  5. Bonus - For additional, supplementary content

    > [!bonus]
> Your bonus content here

🎨 Styling

By default, styles are automatically injected into your document. You can customize this behavior:

Automatic Style Injection (Default)

Styles are included automatically when you use the plugin with default settings:

unified().use(remarkNotes) // Styles auto-injected

Manual Style Import

If you prefer to manage styles yourself (e.g., for SSR or custom build tools), disable auto-injection:

unified().use(remarkNotes, { injectStyles: false })

Then manually import the CSS:

import 'remark-notes-plugin/styles.css'

Customizing Styles

The plugin uses a modular class structure that makes it easy to customize the appearance:

Base Classes

  • .remark-note - Base container for all note types
  • .remark-note-header - Note header container
  • .remark-note-icon - Icon styling
  • .remark-note-title - Note title styling
  • .remark-note-content - Note content container

Type-Specific Classes

  • .remark-note-note - Note type styling
  • .remark-note-tip - Tip type styling
  • .remark-note-important - Important type styling
  • .remark-note-quote - Quote type styling
  • .remark-note-bonus - Bonus type styling

Custom Class Prefix

You can add a custom prefix to all CSS classes:

unified().use(remarkNotes, { classPrefix: 'my-callout' })

This generates classes like:

  • .my-callout-remark-note
  • .my-callout-remark-note-tip
  • .my-callout-remark-note-header
  • etc.

Customization Example

/* Example: Customize the Note type */
.remark-note-note {
  background-color: #your-color;
  border-color: #your-border-color;
}

.remark-note-note .remark-note-title {
  color: #your-text-color;
}

🛠️ Development

This project is written in TypeScript. To contribute or modify:

# Install dependencies
yarn

# Build the project
yarn build

# Run tests
yarn test

# Watch mode for development
yarn watch

🤝 Contributing

Contributions are welcome! Feel free to:

  • Report bugs
  • Suggest new features
  • Submit pull requests

Please ensure your pull request passes all tests and includes appropriate documentation.

⭐️ If you find this plugin useful, please consider giving it a star on GitHub! ⭐️