feat: add JSON frontmatter support (#411)

Author: Pixel998

README.md

@@ -181,6 +181,7 @@ By default, Markdown parsers do not support [front matter](https://jekyllrb.com/
 | `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.       |
+| `"json"`         | Enables JSON front matter parsing in Markdown files.       |
 
 ```js
 // eslint.config.js
@@ -195,7 +196,7 @@ export default defineConfig([
         },
         language: "markdown/gfm",
         languageOptions: {
-            frontmatter: "yaml", // Or pass `"toml"` to enable TOML front matter parsing.
+            frontmatter: "yaml", // Or pass `"toml"` or `"json"` to enable TOML or JSON front matter parsing.
         },
         rules: {
             "markdown/no-html": "error"

src/language/markdown-language.js

@@ -35,6 +35,23 @@ import { gfm } from "micromark-extension-gfm";
 // Helpers
 //-----------------------------------------------------------------------------
 
+/**
+ * Parser configuration for JSON frontmatter.
+ * Example of supported frontmatter format:
+ * ```markdown
+ * ---
+ * {
+ *   "title": "My Document",
+ *   "date": "2025-06-09"
+ * }
+ * ---
+ * ```
+ */
+const jsonFrontmatterConfig = {
+	type: "json",
+	marker: "-",
+};
+
 /**
  * Create parser options based on `mode` and `languageOptions`.
  * @param {ParserMode} mode The markdown parser mode.
@@ -64,6 +81,11 @@ function createParserOptions(mode, languageOptions) {
 		} else if (frontmatterOption === "toml") {
 			extensions.push(frontmatter(["toml"]));
 			mdastExtensions.push(frontmatterFromMarkdown(["toml"]));
+		} else if (frontmatterOption === "json") {
+			extensions.push(frontmatter(jsonFrontmatterConfig));
+			mdastExtensions.push(
+				frontmatterFromMarkdown(jsonFrontmatterConfig),
+			);
 		}
 	}
 
@@ -139,7 +161,12 @@ export class MarkdownLanguage {
 	 */
 	validateLanguageOptions(languageOptions) {
 		const frontmatterOption = languageOptions?.frontmatter;
-		const validFrontmatterOptions = new Set([false, "yaml", "toml"]);
+		const validFrontmatterOptions = new Set([
+			false,
+			"yaml",
+			"toml",
+			"json",
+		]);
 
 		if (
 			frontmatterOption !== undefined &&

src/types.ts

@@ -101,14 +101,33 @@ export interface Toml extends Literal {
  */
 export interface TomlData extends Data {}
 
+/**
+ * Markdown JSON.
+ */
+export interface Json extends Literal {
+	/**
+	 * Node type of mdast JSON.
+	 */
+	type: "json";
+	/**
+	 * Data associated with the mdast JSON.
+	 */
+	data?: JsonData | undefined;
+}
+
+/**
+ * Info associated with mdast JSON nodes by the ecosystem.
+ */
+export interface JsonData extends Data {}
+
 /**
  * Language options provided for Markdown files.
  */
 export interface MarkdownLanguageOptions extends LanguageOptions {
 	/**
 	 * The options for parsing frontmatter.
 	 */
-	frontmatter?: false | "yaml" | "toml";
+	frontmatter?: false | "yaml" | "toml" | "json";
 }
 
 /**
@@ -148,7 +167,8 @@ export interface MarkdownRuleVisitor
 					| TableCell
 					| TableRow
 					| Yaml // Extensions (front matter)
-					| Toml as NodeType["type"]]?: (
+					| Toml
+					| Json as NodeType["type"]]?: (
 					node: NodeType,
 					parent?: Parent,
 				) => void;

tests/language/markdown-language.test.js

@@ -16,7 +16,7 @@ import assert from "node:assert";
 
 describe("MarkdownLanguage", () => {
 	describe("validateLanguageOptions()", () => {
-		it("should throw an error if `frontmatter` is not `false`, `'yaml'`, or `'toml'`", () => {
+		it("should throw an error if `frontmatter` is not `false`, `'yaml'`, `'toml'`, or `'json'`", () => {
 			const language = new MarkdownLanguage();
 
 			assert.throws(() => {
@@ -57,6 +57,9 @@ describe("MarkdownLanguage", () => {
 			assert.doesNotThrow(() => {
 				language.validateLanguageOptions({ frontmatter: "toml" });
 			});
+			assert.doesNotThrow(() => {
+				language.validateLanguageOptions({ frontmatter: "json" });
+			});
 		});
 
 		it("should not throw an error when `frontmatter` has a correct value in gfm mode", () => {
@@ -71,6 +74,9 @@ describe("MarkdownLanguage", () => {
 			assert.doesNotThrow(() => {
 				language.validateLanguageOptions({ frontmatter: "toml" });
 			});
+			assert.doesNotThrow(() => {
+				language.validateLanguageOptions({ frontmatter: "json" });
+			});
 		});
 	});
 
@@ -214,6 +220,56 @@ describe("MarkdownLanguage", () => {
 			assert.strictEqual(result.ast.children[1].type, "heading");
 			assert.strictEqual(result.ast.children[2].type, "paragraph");
 		});
+
+		it("should parse JSON frontmatter in commonmark mode when `frontmatter: 'json'` is set", () => {
+			const language = new MarkdownLanguage({ mode: "commonmark" });
+			const result = language.parse(
+				{
+					body: '---\n{\n"title": "Hello"\n}\n---\n\n# Hello, World!\n\nHello, World!',
+					path: "test.md",
+				},
+				{
+					languageOptions: {
+						frontmatter: "json",
+					},
+				},
+			);
+
+			assert.strictEqual(result.ok, true);
+			assert.strictEqual(result.ast.type, "root");
+			assert.strictEqual(result.ast.children[0].type, "json");
+			assert.strictEqual(
+				result.ast.children[0].value,
+				'{\n"title": "Hello"\n}',
+			);
+			assert.strictEqual(result.ast.children[1].type, "heading");
+			assert.strictEqual(result.ast.children[2].type, "paragraph");
+		});
+
+		it("should parse JSON frontmatter in gfm mode when `frontmatter: 'json'` is set", () => {
+			const language = new MarkdownLanguage({ mode: "gfm" });
+			const result = language.parse(
+				{
+					body: '---\n{\n"title": "Hello"\n}\n---\n\n# Hello, World!\n\nHello, World!',
+					path: "test.md",
+				},
+				{
+					languageOptions: {
+						frontmatter: "json",
+					},
+				},
+			);
+
+			assert.strictEqual(result.ok, true);
+			assert.strictEqual(result.ast.type, "root");
+			assert.strictEqual(result.ast.children[0].type, "json");
+			assert.strictEqual(
+				result.ast.children[0].value,
+				'{\n"title": "Hello"\n}',
+			);
+			assert.strictEqual(result.ast.children[1].type, "heading");
+			assert.strictEqual(result.ast.children[2].type, "paragraph");
+		});
 	});
 
 	describe("createSourceCode()", () => {

tests/types/types.test.ts

@@ -7,7 +7,7 @@ import markdown, {
 	SourceRange,
 	type RuleModule,
 } from "@eslint/markdown";
-import { Toml } from "@eslint/markdown/types";
+import { Toml, Json } from "@eslint/markdown/types";
 import { ESLint, Linter } from "eslint";
 import type {
 	// Nodes (abstract)
@@ -164,6 +164,8 @@ typeof processorPlugins satisfies {};
 			"yaml:exit": (...args) => testVisitor<Yaml>(...args),
 			toml: (...args) => testVisitor<Toml>(...args),
 			"toml:exit": (...args) => testVisitor<Toml>(...args),
+			json: (...args) => testVisitor<Json>(...args),
+			"json:exit": (...args) => testVisitor<Json>(...args),
 
 			// Unknown selectors allowed
 			"heading[depth=1]"(node: MarkdownNode, parent?: ParentNode) {},