From 02d1763be512330291fcf0144cedb721efa6bb00 Mon Sep 17 00:00:00 2001
From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
Date: Sun, 30 Aug 2026 20:41:58 +0530
Subject: [PATCH] refactor: rename option to `eagerFrontmatterInterpolation`

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 __tests__/unit/node/markdown/markdown.test.ts       |  6 ++++--
 ...est.ts => eagerFrontmatterInterpolation.test.ts} |  4 ++--
 src/node/markdown/markdown.ts                       |  8 ++++----
 ...ressions.ts => eagerFrontmatterInterpolation.ts} | 13 +++++++++----
 4 files changed, 19 insertions(+), 12 deletions(-)
 rename __tests__/unit/node/markdown/plugins/{frontmatterExpressions.test.ts => eagerFrontmatterInterpolation.test.ts} (97%)
 rename src/node/markdown/plugins/{frontmatterExpressions.ts => eagerFrontmatterInterpolation.ts} (96%)

diff --git a/__tests__/unit/node/markdown/markdown.test.ts b/__tests__/unit/node/markdown/markdown.test.ts
index 76063dac..af5d2fef 100644
--- a/__tests__/unit/node/markdown/markdown.test.ts
+++ b/__tests__/unit/node/markdown/markdown.test.ts
@@ -42,11 +42,13 @@ describe('node/markdown/markdown', () => {
       expect(await render(':tada:', { emoji: false })).toContain(':tada:')
     })
 
-    test('frontmatterExpressions', async () => {
+    test('eagerFrontmatterInterpolation', async () => {
       const src = '---\ntitle: Hello\n---\n\n{{ $frontmatter.title }}'
       expect(await render(src)).toContain('<p>Hello</p>')
 
-      const disabled = await render(src, { frontmatterExpressions: false })
+      const disabled = await render(src, {
+        eagerFrontmatterInterpolation: false
+      })
       expect(disabled).toContain('<p>{{ $frontmatter.title }}</p>')
     })
 
diff --git a/__tests__/unit/node/markdown/plugins/frontmatterExpressions.test.ts b/__tests__/unit/node/markdown/plugins/eagerFrontmatterInterpolation.test.ts
similarity index 97%
rename from __tests__/unit/node/markdown/plugins/frontmatterExpressions.test.ts
rename to __tests__/unit/node/markdown/plugins/eagerFrontmatterInterpolation.test.ts
index 8a3b61c3..e38885f5 100644
--- a/__tests__/unit/node/markdown/plugins/frontmatterExpressions.test.ts
+++ b/__tests__/unit/node/markdown/plugins/eagerFrontmatterInterpolation.test.ts
@@ -45,7 +45,7 @@ async function renderBody(body: string) {
   return (await render(frontmatter + body)).trim()
 }
 
-describe('node/markdown/plugins/frontmatterExpressions', () => {
+describe('node/markdown/plugins/eagerFrontmatterInterpolation', () => {
   test('resolves property paths and escapes the value', async () => {
     const html = await render(`\
 ---
@@ -218,7 +218,7 @@ logo: /logo.png
       ].join('\n\n')
 
       const runtimeEnv: any = {}
-      const runtimeMd = await createMd({ frontmatterExpressions: false })
+      const runtimeMd = await createMd({ eagerFrontmatterInterpolation: false })
       const runtimeHtml = await runtimeMd.renderAsync(
         frontmatter + body,
         runtimeEnv
diff --git a/src/node/markdown/markdown.ts b/src/node/markdown/markdown.ts
index 8eb5cbde..45d84171 100644
--- a/src/node/markdown/markdown.ts
+++ b/src/node/markdown/markdown.ts
@@ -51,7 +51,7 @@ import {
   gitHubAlertsPlugin,
   type ContainerOptions
 } from './plugins/containers'
-import { frontmatterExpressionsPlugin } from './plugins/frontmatterExpressions'
+import { eagerFrontmatterInterpolationPlugin } from './plugins/eagerFrontmatterInterpolation'
 import { highlight as createHighlighter } from './plugins/highlight'
 import { imagePlugin, type Options as ImageOptions } from './plugins/image'
 import {
@@ -341,7 +341,7 @@ export interface MarkdownOptions extends MarkdownItAsyncOptions {
    * @experimental
    * @default true
    */
-  frontmatterExpressions?: boolean
+  eagerFrontmatterInterpolation?: boolean
   /**
    * Options for `@mdit-vue/plugin-sfc`.
    * @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-sfc
@@ -553,8 +553,8 @@ export async function createMarkdownRenderer(
   // https://github.com/jonschlinkert/gray-matter/blob/310f9349381775d10a221cef903989eb5acc8843/index.js#L44-L47
   ;(options.frontmatter ??= {}).grayMatterOptions ??= {}
   frontmatterPlugin(md, options.frontmatter)
-  if (options.frontmatterExpressions !== false) {
-    frontmatterExpressionsPlugin(md)
+  if (options.eagerFrontmatterInterpolation !== false) {
+    eagerFrontmatterInterpolationPlugin(md)
   }
   if (options.headers) {
     headersPlugin(md, {
diff --git a/src/node/markdown/plugins/frontmatterExpressions.ts b/src/node/markdown/plugins/eagerFrontmatterInterpolation.ts
similarity index 96%
rename from src/node/markdown/plugins/frontmatterExpressions.ts
rename to src/node/markdown/plugins/eagerFrontmatterInterpolation.ts
index a7efb8e5..79ac04db 100644
--- a/src/node/markdown/plugins/frontmatterExpressions.ts
+++ b/src/node/markdown/plugins/eagerFrontmatterInterpolation.ts
@@ -29,11 +29,13 @@ const vPreRE = /\bv-pre\b/
 
 type Resolve = (expr: string) => string | undefined
 
-export const frontmatterExpressionsPlugin = (md: MarkdownItAsync) => {
+export const eagerFrontmatterInterpolationPlugin = (md: MarkdownItAsync) => {
   // before the rules other plugins push (anchor, toc, ...), so slugs and
   // extracted titles are derived from the resolved text
-  md.core.ruler.after('text_join', 'vp_frontmatter_expressions', (state) =>
-    frontmatterExpressions(md, state)
+  md.core.ruler.after(
+    'text_join',
+    'vp_eager_frontmatter_interpolation',
+    (state) => eagerFrontmatterInterpolation(md, state)
   )
 
   // resolved values render with their own escaping (see `escapeValue`);
@@ -45,7 +47,10 @@ export const frontmatterExpressionsPlugin = (md: MarkdownItAsync) => {
       : textRule(tokens, idx, options, env, self)
 }
 
-function frontmatterExpressions(md: MarkdownItAsync, state: StateCore): void {
+function eagerFrontmatterInterpolation(
+  md: MarkdownItAsync,
+  state: StateCore
+): void {
   const { frontmatter } = state.env as MarkdownEnv
   if (!frontmatter || !state.src.includes('{{')) return