rehype-callouts

A rehype plugin for processing and rendering blockquote-based callouts.

What is this?

This plugin adds support for callouts (admonitions/alerts), allowing you to use Obsidian's callout syntax uniformly in markdown to achieve the following features:

Includes default callout types for various themes.
Optionally import stylesheets for corresponding themes.
Supports collapsible callouts with -/+ and nestable callouts.
Allows custom titles with markdown syntax.
Customizable default callout types (title, icon, color).
Configurable new callout types.
Configurable aliases for callout types.
Configurable icon display.

When should I use this?

This plugin helps render markdown callouts, making it ideal for displaying Obsidian callouts on an Astro-powered blog.

It also modifies HTML directly (no allowDangerousHtml in remark-rehype) and supports collapsible callouts using the details tag, all without JavaScript.

Installation

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

npm install rehype-callouts
yarn add rehype-callouts
pnpm add rehype-callouts

In Deno with esm.sh:

import rehypeCallouts from 'https://esm.sh/rehype-callouts'

In browsers with esm.sh:

<script type="module">
  import rehypeCallouts from 'https://esm.sh/rehype-callouts?bundle'
</script>

Usage

Say example.md contains:

<!-- Callout type names are case-insensitive: 'Note', 'NOTE', and 'note' are equivalent. -->

> [!note] This is a _non-collapsible_ callout
> Some content is displayed directly!

> [!WARNING]- This is a **collapsible** callout
> Some content shown after opening!

And module example.js contains:

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeCallouts from 'rehype-callouts'
import rehypeStringify from 'rehype-stringify'
import { readSync } from 'to-vfile'

const file = unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeCallouts)
  .use(rehypeStringify)
  .processSync(readSync('example.md'))

console.log(String(file))

Or for an Astro project, the astro.config.ts contains:

import { defineConfig } from 'astro/config'
import rehypeCallouts from 'rehype-callouts'

// https://docs.astro.build/en/reference/configuration-reference/
export default defineConfig({
  // ...
  markdown: {
    // ...
    rehypePlugins: [
      // ...
      rehypeCallouts,
    ],
  },
  // ...
})

Then running node example.js or pnpm astro dev yields:

<div
  class="callout"
  style="--callout-color-light: rgb(8, 109, 221); --callout-color-dark: rgb(2, 122, 255);"
>
  <div class="callout-title">
    <div class="callout-icon">
      <!-- svg icon-->
    </div>
    <div class="callout-title-inner">
      This is a <em>non-collapsible</em> callout
    </div>
  </div>
  <div class="callout-content">
    <p>Some content is displayed directly!</p>
  </div>
</div>

<details
  class="callout callout-collapsible"
  style="--callout-color-light: rgb(236, 117, 0); --callout-color-dark: rgb(233, 151, 63);"
>
  <summary class="callout-title">
    <div class="callout-icon">
      <!-- svg icon-->
    </div>
    <div class="callout-title-inner">
      This is a <strong>collapsible</strong> callout
    </div>
    <div class="callout-fold">
      <!-- svg icon-->
    </div>
  </summary>
  <div class="callout-content">
    <p>Some content shown after opening!</p>
  </div>
</details>

Styling

You can customize callout styles using the class names mentioned above or import the provided theme-specific stylesheets:

import 'rehype-callouts/theme/github'
import 'rehype-callouts/theme/obsidian'
import 'rehype-callouts/theme/vitepress'

If bundling CSS files, import the CSS in your main CSS file:

@import 'rehype-callouts/theme/github';

For Sass, import the CSS in your main Sass file:

@use 'rehype-callouts/theme/github';

Alternatively, import the CSS directly in browsers via unpkg.com or jsdelivr.net:

<link
  rel="stylesheet"
  href="https://unpkg.com/rehype-callouts/dist/themes/github/index.css"
/>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/rehype-callouts/dist/themes/github/index.css"
/>

API

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

`unified().use(rehypeCallouts, options?)`

Used to render callouts, including an optional parameter options.

`options: UserOptions`

You can configure this plugin with the following optional settings:

Option	Type	Description
theme	`'github'\|'obsidian'\|'vitepress'`(default: `obsidian`)	Specify your desired callout theme to automatically apply its default callout types.
callouts	`Record<string, CalloutConfig>` (default: see source code )	Defines the properties for default and custom callouts. For example: `{'note': {title: 'CustomTitle'}, 'custom': {color: 'pink'}}`
aliases	`Record<string, string[]>` (default: `{}`)	Configure aliases for callout types. For example: `{'note': ['n'], 'tip': ['t']}`
showIndicator	`boolean`(default: `true`)	Whether to display an type-specific icons before callout title.

`callouts: Record<string, CalloutConfig>`

Defines properties for default and custom callouts. Each key represents a callout type, and the value is an object with the following optional properties:

Property	Type	Description
title	`string`	Title for this callout type. For new callout types, defaults to the callout type name if unset.
indicator	`string`	Icon in SVG format as a string. For new callout types, the icon will not display unless set, even if `showIndicator` is `true`. You can get icons from Iconify. For example: `'<svg>...</svg>'`
color	`string \| [string, string]`	Color(s) as a `<color>` string. For new callout types, defaults to `#888` if unset. For example:`'rgb(8, 109, 221)'`: works for both light and dark themes.`['#0969da', '#2f81f7']` : first for light theme, second for dark theme.

Themes

This package offers callout styles for GitHub, Obsidian, and VitePress, with dark mode support via the .dark class. For more, check the source code.