Allow options.markdownItFactory to be implemented asynchronously so t…

…he markdown-it parser import can be deferred.

README.md

@@ -580,14 +580,22 @@ declaring the dependency and returning an instance from this factory. If any
 [`markdown-it` plugins][markdown-it-plugin] are needed, they should be loaded by
 the caller before returning the `markdown-it` instance.
 
-For compatibility with previous versions of `markdownlint`, this function can be
-implemented like:
+For compatibility with previous versions of `markdownlint`, this function should
+be similar to:
 
 ```javascript
 import markdownIt from "markdown-it";
 const markdownItFactory = () => markdownIt({ "html": true });
 ```
 
+When an asynchronous implementation of `lint` is being invoked (e.g., via
+`markdownlint/async` or `markdownlint/promise`), this function can return a
+`Promise` in order to defer the import of `markdown-it`:
+
+```javascript
+const markdownItFactory = () => import("markdown-it").then((module) => module.default({ "html": true }));
+```
+
 > Note that this function is only invoked when a `markdown-it` parser is
 > needed. None of the built-in rules use the `markdown-it` parser, so it is only
 > invoked when one or more [custom rules][custom-rules] are present that use the

example/typescript/type-check.ts

@@ -99,7 +99,7 @@ options = {
   "frontMatter": /---/,
   "handleRuleFailures": false,
   "noInlineConfig": false,
-  "markdownItFactory": () => new markdownIt()
+  "markdownItFactory": () => markdownIt()
 };
 
 assertLintResults(lintSync(options));

lib/markdownit.cjs

@@ -5,7 +5,7 @@
 const { newLineRe } = require("../helpers");
 
 // @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
-/** @typedef {import("markdownlint").MarkdownItFactory} MarkdownItFactory */
+/** @typedef {import("markdownlint").MarkdownIt} MarkdownIt */
 // @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("markdownlint").MarkdownItToken} MarkdownItToken */
 // @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
@@ -154,13 +154,12 @@ function annotateAndFreezeTokens(tokens, lines) {
 /**
  * Gets an array of markdown-it tokens for the input.
  *
- * @param {MarkdownItFactory} markdownItFactory Function to create a markdown-it parser.
+ * @param {MarkdownIt} markdownIt Instance of the markdown-it parser.
  * @param {string} content Markdown content.
  * @param {string[]} lines Lines of Markdown content.
  * @returns {MarkdownItToken[]} Array of markdown-it tokens.
  */
-function getMarkdownItTokens(markdownItFactory, content, lines) {
-  const markdownIt = markdownItFactory();
+function getMarkdownItTokens(markdownIt, content, lines) {
   const tokens = markdownIt.parse(content, {});
   annotateAndFreezeTokens(tokens, lines);
   return tokens;

lib/markdownlint.d.mts

@@ -373,7 +373,7 @@ export type MarkdownIt = {
 /**
  * Gets an instance of the markdown-it parser. Any plugins should already have been loaded.
  */
-export type MarkdownItFactory = () => MarkdownIt;
+export type MarkdownItFactory = () => MarkdownIt | Promise<MarkdownIt>;
 /**
  * Configuration options.
  */