rehype-callouts

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

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.

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.

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>

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>

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"
/>

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

Used to render callouts, including an optional parameter options.

You can configure this plugin with the following optional settings:

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

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

This package is fully typed with TypeScript. See jsDocs.io for type details.

• staticnoise/rehype-obsidian-callout - basic functionality.
• Octions - default icons for GitHub callouts.
• Lucide - default icons for Obsidian, VitePress callouts.

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!

MIT © 2024-PRESENT Stephanie Lin