alert

rehype-github-alert

rehype plugin to support alerts like on GitHub.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • rehypeGithubAlert()
• Bugs
• Authoring
• HTML
• CSS
• Syntax
• Types
• Compatibility
• Security
• Related
• Contribute
• Notice
• License

What is this?

This plugin enhances turns the format that github.com uses for alerts into actual alerts. It turns blockquotes that start with a specific paragraph (such as [!note]) into divs with a particular class:

Note

This is a note!

This plugin is part of a monorepo rehype-github. See its readme for more info.

When should I use this?

You can use this plugin when you want to match how github.com works. For your own pipelines, similar to github.com, I would recommend using directives instead. See remark-directive for more info.

Install

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

npm install rehype-github-alert

In Deno with esm.sh:

import rehypeGithubAlert from 'https://esm.sh/rehype-github-alert@1'

In browsers with esm.sh:

<script type="module">
  import rehypeGithubAlert from 'https://esm.sh/rehype-github-alert@1?bundle'
</script>

Use

Say our module example.js looks as follows:

import rehypeGithubAlert from 'rehype-github-alert'
import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'

const file = await unified()
  .use(rehypeParse, {fragment: true})
  .use(rehypeGithubAlert)
  .use(rehypeStringify)
  .process('<blockquote><p>[!note]</p><p>hi</p></blockquote>')

console.log(String(file))

…now running node example.js yields:

<div class="markdown-alert markdown-alert-note"><p class="markdown-alert-title"><svg class="octicon octicon-info mr-2" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>Note</p><p>hi</p></div>

API

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

rehypeGithubAlert()

Plugin to enhance alerts.

Parameters

There are no parameters.

Returns

Transform ((tree: Root, file: VFile) => Promise<Root>).

Bugs

There are just many oddities with how this all works. If you can, I would recommend using remark-directive instead.

For a combination of the two, see remark-github-admonitions-to-directives.

Authoring

You do not need to use screaming uppercase: [!note] is fine!

HTML

The markup for that github.com adds is:

<div class="markdown-alert markdown-alert-note"><p class="markdown-alert-title"><svg class="octicon octicon-info mr-2" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>Note</p><p>hi</p></div>

Each different label (such as tip) is turned into a different class (tip turns into markdown-alert-tip). They each also get a different icon (tip gets octicon-light-bulb).

For different HTML, see rehype-github-alerts.

CSS

See github-markdown-css for the CSS that GitHub uses. Relevant styles are under .markdown-alert and .octicon.

Syntax

No syntax is applicable.

Types

This package is fully typed with TypeScript. It exports no additional types.

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 16+. Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with rehype-parse version 3+, rehype-stringify version 3+, rehype version 5+, and unified version 6+.

Security

This package is safe.

Related

• remark-gfm — support GFM in remark

Contribute

See contributing.md in rehypejs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

Notice

This project is not affiliated with GitHub.

License

MIT © Titus Wormer