markdownlint-rule-helpers

What is markdownlint-rule-helpers?

The markdownlint-rule-helpers package provides utility functions to assist in writing custom rules for markdownlint, a popular Markdown linter. These helpers simplify common tasks such as parsing Markdown content, managing tokens, and handling rule options.

What are markdownlint-rule-helpers's main functionalities?

parseMarkdown

The parseMarkdown function takes a string of Markdown content and returns a parsed representation of it, which can be used for further analysis or rule enforcement.

const { parseMarkdown } = require('markdownlint-rule-helpers');
const markdownContent = '# Title\n\nSome content';
const parsed = parseMarkdown(markdownContent);
console.log(parsed);

getLineMetadata

The getLineMetadata function processes an array of lines from a Markdown document and returns metadata about each line, such as its length and whether it is blank. This is useful for rules that need to analyze line-by-line content.

const { getLineMetadata } = require('markdownlint-rule-helpers');
const lines = ['# Title', '', 'Some content'];
const metadata = getLineMetadata(lines);
console.log(metadata);

addError

The addError function helps in adding error messages to a list of errors, specifying the line number, error message, and optional context. This is essential for reporting issues found by custom rules.

const { addError } = require('markdownlint-rule-helpers');
const errors = [];
addError(errors, 1, 'Error message', 'Context');
console.log(errors);

Other packages similar to markdownlint-rule-helpers

remark-lint

remark-lint is a plugin for remark, a Markdown processor powered by plugins. It provides a flexible and extensible way to lint Markdown files. Compared to markdownlint-rule-helpers, remark-lint offers a broader ecosystem of plugins and integrations, but may require more setup for custom rules.

markdown-it

markdown-it is a Markdown parser with a focus on speed and extensibility. While it is not a linter, it provides a plugin system that can be used to implement custom linting rules. It is more general-purpose compared to markdownlint-rule-helpers, which is specifically designed for linting.

markdownlint

markdownlint is the core linter that markdownlint-rule-helpers is designed to extend. It provides a set of built-in rules for linting Markdown files. While markdownlint-rule-helpers assists in writing custom rules, markdownlint itself is the primary tool for enforcing Markdown standards.

README

markdownlint-rule-helpers

A collection of markdownlint helper functions for custom rules

Overview

The Markdown linter markdownlint offers a variety of built-in validation rules and supports the creation of custom rules. The internal rules share various helper functions; this package exposes those for reuse by custom rules.

API

Undocumented - This package exports the internal functions as-is. The APIs were not originally meant to be public, are not officially supported, and may change from release to release. There are brief descriptive comments above each function, but no JSDoc annotations. That said, some of what's here will be useful to custom rule authors and may avoid duplicating code.

Examples

Using Helpers from a Custom Rule

const { forEachLine, getLineMetadata } = require("markdownlint-rule-helpers");

/** @type import("markdownlint").Rule */
module.exports = {
  "names": [ "every-n-lines" ],
  "description": "Rule that reports an error every N lines",
  "tags": [ "test" ],
  "parser": "none",
  "function": (params, onError) => {
    const n = params.config.n || 2;
    forEachLine(getLineMetadata(params), (line, lineIndex) => {
      const lineNumber = lineIndex + 1;
      if ((lineNumber % n) === 0) {
        onError({
          "lineNumber": lineNumber,
          "detail": "Line number " + lineNumber
        });
      }
    });
  }
};

Applying Recommended Fixes

const { "sync": markdownlintSync } = require("markdownlint");
const markdownlintRuleHelpers = require("markdownlint-rule-helpers");

function fixMarkdownlintViolations(content) {
  const fixResults = markdownlintSync({ strings: { content } });
  return markdownlintRuleHelpers.applyFixes(content, fixResults.content);
}

See also: markdownlint built-in rule implementations.

Tests

None - The entire body of code is tested to 100% coverage by the core markdownlint project, so there are no additional tests here.

Changelog

0.25.0

• Add MD049/MD050 for consistent emphasis/strong style (both auto-fixable)
• Improve MD007/MD010/MD032/MD033/MD035/MD037/MD039
• Support asynchronous custom rules
• Improve performance
• Improve CI process
• Reduce dependencies
• Update dependencies