# remark-github-admonitions-to-directives

> A Remark plugin to convert Github style alerts to admonitions directives.

Latest version **2.1.0** (published 2024-10-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install remark-github-admonitions-to-directives
pnpm add remark-github-admonitions-to-directives
yarn add remark-github-admonitions-to-directives
bun add remark-github-admonitions-to-directives
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2024-10-28 |
| First published | 2024-03-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 20.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 36 |
| Author | Luud Janssen |
| Maintainers | luudjanssen |
| Keywords | remark, remark-plugin, markdown, github, alert, remark-directive, docusaurus, admonitions, admonition |

## Links

- npm: https://www.npmjs.com/package/remark-github-admonitions-to-directives
- Repository: https://github.com/incentro-dc/remark-github-admonitions-to-directives
- Issues: https://github.com/incentro-dc/remark-github-admonitions-to-directives/issues
- npm.io page: https://npm.io/package/remark-github-admonitions-to-directives

## Dependencies (4)

- [unified](https://npm.io/package/unified.md) ^11.0.0
- [@types/mdast](https://npm.io/package/@types/mdast.md) ^4.0.0
- [unist-util-visit](https://npm.io/package/unist-util-visit.md) ^5.0.0
- [mdast-util-directive](https://npm.io/package/mdast-util-directive.md) ^3.0.0

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 2.1.0 (latest) — 2024-10-28
- 2.0.0 — 2024-09-05
- 1.0.5 — 2024-04-18
- 1.0.4 — 2024-03-05
- 1.0.3 — 2024-03-04
- 1.0.2 — 2024-03-04
- 1.0.1 — 2024-03-04
- 1.0.0 — 2024-03-03

## README

<div align="center">
  <h1 align="center">Remark Github Alerts to Directives</h1>

  <a href="https://www.npmjs.com/package/remark-github-admonitions-to-directives">
    <img alt="NPM version" src="https://img.shields.io/npm/v/remark-github-admonitions-to-directives?logo=npm&style=flat-square">
  </a>
  <a href="https://github.com/incentro-dc/remark-github-admonitions-to-directives/actions/workflows/build.yml">
    <img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/incentro-dc/remark-github-admonitions-to-directives/build.yml?label=Builds&logo=github&style=flat-square">
  </a>
  <a href="https://github.com/incentro-dc/remark-github-admonitions-to-directives/actions/workflows/test.yml">
    <img alt="Test status" src="https://img.shields.io/github/actions/workflow/status/incentro-dc/remark-github-admonitions-to-directives/test.yml?label=Tests&logo=vitest&style=flat-square">
  </a>
  <a href="https://prettier.io/">
    <img alt="code style: prettier" src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?logo=prettier&style=flat-square">
  </a>
</div>

## 💫 Introduction

Github introduced [alerts in markdown files](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) with their own proprietary syntax [instead of using Remark directives](https://github.com/orgs/community/discussions/16925#discussioncomment-2791869). This plugin converts Github's blockquote alert style to [Remark admonitions](https://github.com/elviswolcott/remark-admonitions) syntax.

It will transform this:

```markdown
> [!NOTE]
> Content
```

Into this:

```markdown
:::note
Content
:::
```

## 💾 Installation

You can install this plugin with:

```bash
pnpm add -D remark-github-admonitions-to-directives
```

## 🪛 Usage

This plugin is just a generic [unified](https://github.com/unifiedjs/unified) ([remark](https://github.com/remarkjs/remark)) plugin to transform one syntax into another. Below are some examples of how to use it with various plugins / systems:

### 📃 With Remark (and Directives)

```typescript
import { remark } from "remark";
import remarkDirective from "remark-directive";
import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";

const processor = remark()
  .use(remarkGithubAdmonitionsToDirectives)
  .use(remarkDirective);

const result = processor.processSync(`
> [!NOTE]
> content
`);

console.log(result.toString());

// should output:
// :::note
// content
// :::
```

### 🦖 With Docusaurus

[Admonitions](https://docusaurus.io/docs/markdown-features/admonitions) are a core feature of Docusaurus and this plugin was actually built with the use case of reusing markdown files, written with Github's syntax, in Docusaurus.

To use this plugin, just use [the instructions for adding MDX plugins](https://docusaurus.io/docs/markdown-features/plugins) and add this plugin to the `beforeDefaultRemarkPlugins` section of your `docusaurus.config.js` file:

```javascript
import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";

export default {
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          path: "docs",
          beforeDefaultRemarkPlugins: [remarkGithubAdmonitionsToDirectives],
        },
      },
    ],
  ],
};
```

> [!IMPORTANT]
> Because this plugin converts Github's syntax to the directives syntax, and Docusaurus then uses the directives syntax to create the adminitions, this plugin has to be processed before any of the Docusaurus plugins. This is why it's added to the `beforeDefaultRemarkPlugins` array and not the `remarkPlugins` array.

### ⚙️ Customizing the mapping

By default, this plugin will map the Github alerts to the Remark admonitions as follows:

- `NOTE` -> `note`
- `TIP` -> `tip`
- `WARNING` -> `warning`
- `IMPORTANT` -> `info`
- `CAUTION` -> `danger`

If you want to customize this mapping, you can pass an object with the mapping to the plugin:

```typescript
import { remark } from "remark";
import remarkDirective from "remark-directive";
import remarkGithubAdmonitionsToDirectives, {
  DEFAULT_MAPPING,
  DirectiveName,
  GithubAlertType,
  type AlertTypeMapping,
} from "remark-github-admonitions-to-directives";

const mapping: AlertTypeMapping = {
  ...DEFAULT_MAPPING,
  [GithubAlertType.IMPORTANT]: DirectiveName.WARNING,
};

const processor = remark()
  .use(remarkGithubAdmonitionsToDirectives, { mapping })
  .use(remarkDirective);

const result = processor.processSync(`
> [!IMPORTANT]
> content
`);

console.log(result.toString());

// should output:
// :::info
// content
// :::
```

# 🙌 Contributing

This plugin was created and is maintained by [Incentro](https://www.incentro.com/). If you're running into issues, please [open an issue](https://github.com/incentro-dc/remark-github-admonitions-to-directives/issues/new). If you want to contribute, please read our [contributing guidelines](./CONTRIBUTING.md).

---
_Source: https://npm.io/package/remark-github-admonitions-to-directives · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._