remark-gh-alerts

Fork from markdown-it-github-alerts.

Support GitHub-style alerts for remark, and replace the SVG dom node with pure CSS.

Here, the solution for replacing the SVG dom node with pure CSS comes from the article Icons in Pure CSS by antfu.

[!NOTE] Highlights information that users should take into account, even when skimming.

[!TIP] Optional information to help a user be more successful.

[!IMPORTANT] Crucial information necessary for users to succeed.

[!WARNING] Critical content demanding immediate user attention due to potential risks.

[!CAUTION] Negative potential consequences of an action.

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Usage

npm i remark-gh-alerts

import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkGithubAlerts from 'remark-gh-alerts'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'

const file = await unified()
  .use(remarkParse)
  .use(remarkGithubAlerts)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(await fs.readFile('./input.md'))

For the options available, please refer to the jsdoc.

Functionality

This plugin transforms the following markdown:

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

to the following HTML:

<div class="markdown-alert markdown-alert-note">
  <p class="markdown-alert-title" dir="auto"><span class="octicon octicon-note" style="--oct-icon: url([data uri])"></span>Note</p><p>
  Highlights information that users should take into account, even when skimming.</p>
</div>

[data uri] is a picture data that after processing svg picture can be used by css.

Which is different with the GitHub's output.

Styling

You can write your custom styles for your alerts.

We also provide some CSS extracted from GitHub's styles for you to use.

import 'remark-gh-alerts/styles/github-colors-light.css'
import 'remark-gh-alerts/styles/github-colors-dark-media.css'
import 'remark-gh-alerts/styles/github-base.css'

You might change github-colors-dark-media.css to github-colors-dark-class.css if you are using class-based (.dark) dark mode.

Refer to the source code for more details.

Next MDX

You just need to add the plugin to your next.config.js:

import remarkGithubAlerts from 'remark-gh-alerts'
import createMDX from '@next/mdx'

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Configure `pageExtensions`` to include MDX files
  pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx'],
  // Optionally, add any other Next.js config below
}

const withMDX = createMDX({
  // Add markdown plugins here, as desired
  options: {
    remarkPlugins: [remarkGithubAlerts],
    rehypePlugins: [],
  },
})

// Merge MDX config with Next.js config
export default withMDX(nextConfig)

License

MIT License © 2024-PRESENT Qhan W