About

marked-alert-fa is an extension of marked-alert which allows you to display github-like alerts within markdown.

For this package to run, you must have marked installed. This package however, does not require marked-alert. It is stand-alone.

You must have some form of Font-Awesome implemented in your project. The easiest way is to install the node package @fortawesome/fontawesome-free

While the original package utilizes SVG paths for the fonts; this package utilizes font-awesome path IDs.

The following icons are utilized by default:

| Alert ID | Icon | | --- | --- | | Note | | | Tip | | | Important | | | Warning | | | Caution | |

• About
• Install
• Usage
• Options
  • Default Alert Variants
• Updates
• Related Packages:
• Contributors ✨

Install

You can install marked-alert-fa using npm or yarn:

npm i @Aetherinox/marked-alert-fa
# or
yarn add @Aetherinox/marked-alert

Usage

These alerts are similar to the ones utilized on Github:

[!NOTE] This is a note

[!TIP] This is a tip

[!IMPORTANT] This is important

[!WARNING] This is a warning

[!CAUTION] This is a caution

To get these icons to display within alerts, utilize marked to convert your markdown. You may use an example similar to the following:

# Example

> [!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.

Within your .js file, utilize something similar to:

import { readFileSync } from 'node:fs'
import { Marked } from 'marked'
import markedAlertFa from '@aetherinox/marked-alert-fa';

const html = new Marked()
  .use(markedAlertFa())
  .parse(readFileSync('example.md', 'utf8'))

console.log(html)

After marked does its work, you should have the following output::

<h1>Example</h1>
<div class="markdown-alert markdown-alert-note"><i class="fa fa-note-sticky"></i>
  <p class="markdown-alert-title">Note</p>
  <p>Highlights information that users should take into account, even when skimming.</p>
</div>
<div class="markdown-alert markdown-alert-tip"><i class="fa fa-lightbulb"></i>
  <p class="markdown-alert-title">Tip</p>
  <p>Optional information to help a user be more successful.</p>
</div>
<div class="markdown-alert markdown-alert-important"><i class="fa fa-circle-exclamation"></i>
  <p class="markdown-alert-title">Important</p>
  <p>Crucial information necessary for users to succeed.</p>
</div>
<div class="markdown-alert markdown-alert-warning"><i class="fa fa-triangle-exclamation"></i>
  <p class="markdown-alert-title">Warning</p>
  <p>Critical content demanding immediate user attention due to potential risks.</p>
</div>
<div class="markdown-alert markdown-alert-caution"><i class="fa fa-bolt"></i>
  <p class="markdown-alert-title">Caution</p>
  <p>Negative potential consequences of an action.</p>
</div>

You can also include setOptions and define other extensions, and call parse() separately.

import { Marked } from 'marked';
import markedAlertFa from '@aetherinox/marked-alert-fa';

  const html = new Marked()
      .setOptions({
          renderer: new YourRenderer(),
          breaks: true,
          gfm: true,
          tables: true
      })
      .use(markedAlertFa())
      .use(markedFootnote())
      .parse(readFileSync('example.md', 'utf8'));

  console.log(html)

Options

The markedAlertFa extension accepts the same options as markedAlert:

• className: A string representing a custom CSS class for the alerts.
• variants: An array of alert variants, where each variant is configured with a type, icon, and title class name. This allows you to create different alert types.

Default Alert Variants

The extension includes default alert variants:

• [!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.

Each variant has an associated icon and title class name which is shown in the About section above.

You can customize the default alert variants and add your own.

const options = {
  variants: [
    {
      type: 'danger',
      icon: 'clipboard',
      title: 'Hello world', // optional
      titleClassName: 'text-danger' // optional
    }
  ]
}

The major different between this package and markedAlert is that the icon field accepts only Font Awesome IDs. The reason for this was due to how our software it set up, and the end-user not having the ability to create their own calls in the back-end.

You can get the ID of an icon by going to the font-awesome website at https://fontawesome.com/v6/icons?q=note&o=r&m=free.

Select an icon and copy the font tag to the right of the icon.

In the example above, you would copy file-circle-check, and leave the fa off.

const options = {
  variants: [
    {
      type: 'success',
      icon: 'file-circle-check',
      title: 'File Uploaded',
      titleClassName: 'text-danger'
    }
  ]
}

Updates

This was originally developed for one software title. If others find it useful, I'll update it and add additional things.

Related Packages:

• MarkedJS
• Marked-Alert
• Marked Extensions List

Contributors ✨

We are always looking for contributors. If you feel that you can provide something useful to this package, then we'd love to review your suggestion. Before submitting your contribution, please review the following resources:

• Pull Request Procedure
• Contributor Policy

Want to help but can't write code?

• Review active questions by our community and answer the ones you know.

The following people have helped get this project going: