feat: support front matter (#328)

* wip: install `mdast-util-frontmatter` and `micromark-extension-frontmatter`

* wip: update `types.ts`

* wip: update `markdown-language.js`

* wip: refactor `markdown-language.js`

* wip: update `README.md`

* wip: add some tests

* wip: add more tests

* wip: update `README.md`

* wip: update comments in `markdown-language.js`

* wip: update `README.md`

* wip: fix typos in `README.md`

* wip: update `types.ts`

* wip: update `markdown-language.js`

* wip: update `markdown-language.test.js`

* wip: update README.md

Co-authored-by: Nicholas C. Zakas <[email protected]>

* wip: update README.md

Co-authored-by: Nicholas C. Zakas <[email protected]>

* wip: rename `mdastExtensions` to `MdastExtensions`

---------

Co-authored-by: Nicholas C. Zakas <[email protected]>

Author: lumirlumir

README.md

@@ -121,6 +121,41 @@ export default [
 ];
 ```
 
+### Language Options
+
+#### Enabling Front Matter in both `commonmark` and `gfm`
+
+By default, Markdown parsers do not support [front matter](https://jekyllrb.com/docs/front-matter/). To enable front matter in both `commonmark` and `gfm`, you can use the `frontmatter` option in `languageOptions`.  
+
+> `@eslint/markdown` internally uses [`micromark-extension-frontmatter`](https://github.com/micromark/micromark-extension-frontmatter) and [`mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-frontmatter) to parse front matter.
+
+| **Option Value** | **Description**                                            |
+|------------------|------------------------------------------------------------|
+| `false`          | Disables front matter parsing in Markdown files. (Default) |
+| `"yaml"`         | Enables YAML front matter parsing in Markdown files.       |
+| `"toml"`         | Enables TOML front matter parsing in Markdown files.       |
+
+```js
+// eslint.config.js
+import markdown from "@eslint/markdown";
+
+export default [
+    {
+        files: ["**/*.md"],
+        plugins: {
+            markdown
+        },
+        language: "markdown/gfm",
+        languageOptions: {
+            frontmatter: "yaml", // Or pass `"toml"` to enable TOML front matter parsing.
+        },
+        rules: {
+            "markdown/no-html": "error"
+        }
+    }
+];
+```
+
 ### Processors
 
 | **Processor Name** | **Description** |

package.json

@@ -83,7 +83,9 @@
     "@eslint/core": "^0.10.0",
     "@eslint/plugin-kit": "^0.2.5",
     "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-frontmatter": "^2.0.1",
     "mdast-util-gfm": "^3.0.0",
+    "micromark-extension-frontmatter": "^2.0.0",
     "micromark-extension-gfm": "^3.0.0"
   },
   "engines": {

src/language/markdown-language.js

@@ -11,20 +11,68 @@
 
 import { MarkdownSourceCode } from "./markdown-source-code.js";
 import { fromMarkdown } from "mdast-util-from-markdown";
+import { frontmatterFromMarkdown } from "mdast-util-frontmatter";
 import { gfmFromMarkdown } from "mdast-util-gfm";
+import { frontmatter } from "micromark-extension-frontmatter";
 import { gfm } from "micromark-extension-gfm";
 
 //-----------------------------------------------------------------------------
 // Types
 //-----------------------------------------------------------------------------
 
 /** @typedef {import("mdast").Root} RootNode */
+/** @typedef {import("mdast-util-from-markdown").Options['extensions']} Extensions */
+/** @typedef {import("mdast-util-from-markdown").Options['mdastExtensions']} MdastExtensions */
 /** @typedef {import("@eslint/core").Language} Language */
 /** @typedef {import("@eslint/core").File} File */
 /** @typedef {import("@eslint/core").ParseResult<RootNode>} ParseResult */
 /** @typedef {import("@eslint/core").OkParseResult<RootNode>} OkParseResult */
+/** @typedef {import("../types.ts").MarkdownLanguageOptions} MarkdownLanguageOptions */
+/** @typedef {import("../types.ts").MarkdownLanguageContext} MarkdownLanguageContext */
 /** @typedef {"commonmark"|"gfm"} ParserMode */
 
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+/**
+ * Create parser options based on `mode` and `languageOptions`.
+ * @param {ParserMode} mode The markdown parser mode.
+ * @param {MarkdownLanguageOptions} languageOptions Language options.
+ * @returns {{extensions: Extensions, mdastExtensions: MdastExtensions}} Parser options for micromark and mdast
+ */
+function createParserOptions(mode, languageOptions) {
+	/** @type {Extensions} */
+	const extensions = [];
+	/** @type {MdastExtensions} */
+	const mdastExtensions = [];
+
+	// 1. `mode`: Add GFM extensions if mode is "gfm"
+	if (mode === "gfm") {
+		extensions.push(gfm());
+		mdastExtensions.push(gfmFromMarkdown());
+	}
+
+	// 2. `languageOptions.frontmatter`: Handle frontmatter options
+	const frontmatterOption = languageOptions?.frontmatter;
+
+	// Skip frontmatter entirely if false
+	if (frontmatterOption !== false) {
+		if (frontmatterOption === "yaml") {
+			extensions.push(frontmatter(["yaml"]));
+			mdastExtensions.push(frontmatterFromMarkdown(["yaml"]));
+		} else if (frontmatterOption === "toml") {
+			extensions.push(frontmatter(["toml"]));
+			mdastExtensions.push(frontmatterFromMarkdown(["toml"]));
+		}
+	}
+
+	return {
+		extensions,
+		mdastExtensions,
+	};
+}
+
 //-----------------------------------------------------------------------------
 // Exports
 //-----------------------------------------------------------------------------
@@ -58,6 +106,14 @@ export class MarkdownLanguage {
 	 */
 	nodeTypeKey = "type";
 
+	/**
+	 * Default language options. User-defined options are merged with this object.
+	 * @type {MarkdownLanguageOptions}
+	 */
+	defaultLanguageOptions = {
+		frontmatter: false,
+	};
+
 	/**
 	 * The Markdown parser mode.
 	 * @type {ParserMode}
@@ -75,24 +131,33 @@ export class MarkdownLanguage {
 		}
 	}
 
-	/* eslint-disable no-unused-vars -- Required to complete interface. */
 	/**
 	 * Validates the language options.
-	 * @param {Object} languageOptions The language options to validate.
+	 * @param {MarkdownLanguageOptions} languageOptions The language options to validate.
 	 * @returns {void}
 	 * @throws {Error} When the language options are invalid.
 	 */
 	validateLanguageOptions(languageOptions) {
-		// no-op
+		const frontmatterOption = languageOptions?.frontmatter;
+		const validFrontmatterOptions = new Set([false, "yaml", "toml"]);
+
+		if (
+			frontmatterOption !== undefined &&
+			!validFrontmatterOptions.has(frontmatterOption)
+		) {
+			throw new Error(
+				`Invalid language option value \`${frontmatterOption}\` for frontmatter.`,
+			);
+		}
 	}
-	/* eslint-enable no-unused-vars -- Required to complete interface. */
 
 	/**
 	 * Parses the given file into an AST.
 	 * @param {File} file The virtual file to parse.
+	 * @param {MarkdownLanguageContext} context The options to use for parsing.
 	 * @returns {ParseResult} The result of parsing.
 	 */
-	parse(file) {
+	parse(file, context) {
 		// Note: BOM already removed
 		const text = /** @type {string} */ (file.body);
 
@@ -103,13 +168,10 @@ export class MarkdownLanguage {
 		 * problem that ESLint identified just like any other.
 		 */
 		try {
-			const options =
-				this.#mode === "gfm"
-					? {
-							extensions: [gfm()],
-							mdastExtensions: [gfmFromMarkdown()],
-						}
-					: { extensions: [] };
+			const options = createParserOptions(
+				this.#mode,
+				context?.languageOptions,
+			);
 			const root = fromMarkdown(text, options);
 
 			return {

src/types.ts

@@ -14,6 +14,8 @@ import type {
 } from "mdast";
 import type { Linter } from "eslint";
 import type {
+	LanguageOptions,
+	LanguageContext,
 	RuleDefinition,
 	RuleVisitor,
 	SourceLocation,
@@ -55,12 +57,27 @@ export type Message = Linter.LintMessage;
 
 export type RuleType = "problem" | "suggestion" | "layout";
 
+/**
+ * Language options provided for Markdown files.
+ */
+export interface MarkdownLanguageOptions extends LanguageOptions {
+	/**
+	 * The options for parsing frontmatter.
+	 */
+	frontmatter?: false | "yaml" | "toml";
+}
+
+/**
+ * The context object that is passed to the Markdown language plugin methods.
+ */
+export type MarkdownLanguageContext = LanguageContext<MarkdownLanguageOptions>;
+
 /**
  * The `SourceCode` interface for Markdown files.
  */
 export interface IMarkdownSourceCode
 	extends TextSourceCode<{
-		LangOptions: {};
+		LangOptions: MarkdownLanguageOptions;
 		RootNode: Root;
 		SyntaxElementWithLoc: Node;
 		ConfigNode: { value: string; position: SourceLocation };
@@ -103,7 +120,7 @@ export type MarkdownRuleDefinition<
 > = RuleDefinition<
 	// Language specific type options (non-configurable)
 	{
-		LangOptions: {};
+		LangOptions: MarkdownLanguageOptions;
 		Code: IMarkdownSourceCode;
 		Visitor: MarkdownRuleVisitor;
 		Node: Node;