remark-gfm-configurable

A fork of remark-gfm with configurable plugin options to enable or disable specific GitHub Flavored Markdown (GFM) features.

By default, remark-gfm enables all underlying features: autolink literals, footnotes, strikethrough, tables, and task list items.

This fork lets you configure which features are enabled by specifying them through a unified options object, offering more granular control over GitHub Flavored Markdown (GFM) features and their behavior.

Table of Contents

• remark-gfm-configurable
  • Table of Contents
  • Introduction
  • Features
  • Installation
  • Usage
    • Basic Usage
    • Configuring Options
  • Options
    • Plugin Options
      • Available Plugin Options
    • Extension Options
      • Strikethrough Extension Options
      • Table Extension Options
      • Complete Options Example
  • Differences from remark-gfm
  • Contributing
    • Development
  • License
  • Acknowledgments

Introduction

remark-gfm-configurable is a remark plugin that adds support for GitHub Flavored Markdown (GFM) with the ability to configure which features are enabled. The options are unified into a single object, making it easy to swap this module with the original remark-gfm without changing your code structure.

Features

• Unified Options Object: Combine plugin and extension options into a single object for simplicity.
• Configurable Plugins: Enable or disable specific GFM features as needed.
• Extension Options: Pass options directly to individual GFM extensions for fine-grained control.
• Compatibility: By default, all GFM features are enabled, maintaining compatibility with remark-gfm.

Installation

Install via npm:

npm install remark-gfm-configurable

Or with Yarn:

yarn add remark-gfm-configurable

Usage

Basic Usage

import { remark } from 'remark';
import remarkGfm from 'remark-gfm-configurable';

const markdown = `
This is a ~~strikethrough~~ text with a task list:

- [x] Task 1
- [ ] Task 2
`;

remark()
  .use(remarkGfm)
  .process(markdown)
  .then((file) => {
    console.log(String(file));
  });

Configuring Options

You can customize both plugin features and extension options by passing an options object to remarkGfm. The options object can include plugin enable/disable settings under the plugins property and extension-specific options at the top level.

import { remark } from 'remark';
import remarkGfm from 'remark-gfm-configurable';

const options = {
  plugins: {
    table: false,        // Disable tables
    footnote: false,     // Disable footnotes
  },
  singleTilde: true,     // Extension option for strikethrough
  tableCellPadding: false, // Extension option for tables (ignored since tables are disabled)
};

remark()
  .use(remarkGfm, options)
  .process(markdown)
  .then((file) => {
    console.log(String(file));
  });

In this example:

• Plugin Options: We disable table and footnote features by setting them to false under the plugins property.
• Extension Options: We set singleTilde: true to allow single tilde strikethrough.

Options

The options object passed to remarkGfm can contain both plugin options (to enable or disable specific GFM features) and extension options (for fine-grained control over individual extensions).

interface Options extends MicromarkStrikethroughOptions, MdastTableOptions {
  plugins?: PluginOptions;
}

Plugin Options

Plugin options are provided under the plugins property within the options object. All features are enabled by default.

interface PluginOptions {
  autolinkLiteral?: boolean; // Default: true
  footnote?: boolean;        // Default: true
  strikethrough?: boolean;   // Default: true
  table?: boolean;           // Default: true
  tasklist?: boolean;        // Default: true
}

Available Plugin Options

• autolinkLiteral: Enable or disable autolink literals.
• footnote: Enable or disable footnotes.
• strikethrough: Enable or disable strikethrough.
• table: Enable or disable tables.
• tasklist: Enable or disable task list items.

Extension Options

Extension options are provided at the top level of the options object. These options are directly passed to the corresponding GFM extensions.

Strikethrough Extension Options

interface MicromarkStrikethroughOptions {
  singleTilde?: boolean; // Default: false
}

• singleTilde: When set to true, allows single tilde (~like this~) to be used for strikethrough, in addition to double tildes (~~like this~~).

Table Extension Options

interface MdastTableOptions {
  tableCellPadding?: boolean; // Default: true
  tablePipeAlign?: boolean;   // Default: false
}

• tableCellPadding: When set to false, disables padding in table cells when generating Markdown.
• tablePipeAlign: When set to true, alignment markers (:) are placed next to the pipes in tables.

Note: Even if you provide extension options for a feature, they will be ignored if the corresponding plugin is disabled.

Complete Options Example

const options = {
  plugins: {
    autolinkLiteral: true,
    footnote: false,       // Disable footnotes
    strikethrough: true,
    table: true,
    tasklist: true,
  },
  // Extension options
  singleTilde: true,       // Strikethrough option
  tableCellPadding: false, // Table option
  tablePipeAlign: true,    // Table option
};

Differences from remark-gfm

• Unified Options Object: Unlike remark-gfm, this package uses a unified options object that includes both plugin and extension options, simplifying configuration.
• Configurable Features: Allows you to enable or disable specific GFM features under the plugins property.
• Extension Options: Provides the ability to pass options directly to GFM extensions at the top level of the options object.
• Module Swapping Compatibility: Designed to allow seamless swapping with remark-gfm without significant code changes.

Contributing

Contributions are welcome! If you have suggestions or find a bug, please open an issue or submit a pull request on GitHub.

Development

To set up the development environment:

1. Clone the repository:

   git clone https://github.com/escherlies/remark-gfm-configurable.git

2. Install dependencies:

   cd remark-gfm-configurable
   npm install

3. Run tests:

   npm test

License

MIT

Acknowledgments

• Titus Wormer for creating the original remark-gfm package.
• The remark and unified communities for their invaluable work.