slackify-markdown

To use the latest version of slackify-markdown, ensure your environment meets the following criteria:

• Node.js: version 22 or higher
• Module System: ESM (ECMAScript Modules) only. For CommonJS support, downgrade to v4.x.

Install the package using npm to convert Markdown into Slack-compatible message formatting.

npm install slackify-markdown

Import slackifyMarkdown from slackify-markdown and pass a Markdown string to it. The function returns a string formatted specifically for Slack's message formatting requirements (e.g., converting headers to bold, lists to bullet points, and links to the <url|text> format).

Note: This package is ESM-only. If you are using CommonJS, you must use version v4.x of the package.

import { slackifyMarkdown } from 'slackify-markdown';

const markdown = `
# List of items

* item 1
* item 2
* item 3

[here is an example](https://example.com)
`;

const result = slackifyMarkdown(markdown);
console.log(result);
/*
 *List of items*

 • item 1
 • item 2
 • item 3

 <https://example.com|here is an example>
*/

The slackifyMarkdown function converts standard Markdown strings into a format compatible with Slack's markdown implementation. It uses unified under the hood with remark-parse, remark-gfm, and several internal plugins to handle definitions and HTML comments.

To use it, pass the markdown string as the first argument. You can optionally provide a SlackifyMarkdownOptions object to configure the underlying remark-parse behavior.

import { slackifyMarkdown } from 'slackify-markdown';

const markdown = '# Hello World\n\nThis is **bold** text.';
const slackified = slackifyMarkdown(markdown);

console.log(slackified);

When calling slackifyMarkdown, you can pass an optional options object of type SlackifyMarkdownOptions. This allows you to pass configuration directly to the underlying remark-parse plugin.

Options

import { slackifyMarkdown, type SlackifyMarkdownOptions } from 'slackify-markdown';

const options: SlackifyMarkdownOptions = {
  parseOptions: {
    // remark-parse specific options here
  }
};

const result = slackifyMarkdown('# Title', options);

The removeDefinitions function is a plugin factory that returns a function to remove definition nodes from the mdast tree. This is used to prevent reference definitions from creating unwanted negative space or artifacts in the final stringified Slack output.

// Returns a function that modifies the tree to remove definitions
const cleanedTree = removeDefinitions()(tree);

The collectDefinitions function is a plugin factory that creates a function to traverse a markdown AST (mdast) and populate a provided DefinitionsMap with reference definitions. This is useful for capturing link references so they can be resolved or used later in the conversion process.

It visits all definition nodes and maps the identifier to a Definition object containing the title and url.

const myDefinitions: DefinitionsMap = {};
// Assuming 'tree' is a Root mdast node
collectDefinitions(myDefinitions)(tree);

When working with markdown reference definitions (e.g., [id]: url), the library uses the Definition interface to represent the extracted data and DefinitionsMap to store them. A Definition contains a title (optional) and a url (required). A DefinitionsMap is a record where keys are the identifier strings from the markdown.

export interface Definition {
  title: string | null | undefined;
  url: string;
}

export type DefinitionsMap = Record<string, Definition>;

The removeHtmlComments function is a plugin factory that returns a function to strip HTML comments (e.g., <!-- comment -->) from the mdast tree. This prevents HTML comments from appearing in Slack output, where they can cause rendering issues.

// Returns a function that removes nodes of type 'html' that match comment syntax
const cleanedTree = removeHtmlComments()(tree);