From e8b5909074d6d32ec87120d32c430d3bb69fb66f Mon Sep 17 00:00:00 2001
From: Daniel Rosenberg <daniel@orgflow.io>
Date: Wed, 16 Jul 2025 22:22:46 +0200
Subject: [PATCH] Clarify use of interpolations inside Markdown headings

---
 docs/en/reference/frontmatter-config.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/en/reference/frontmatter-config.md b/docs/en/reference/frontmatter-config.md
index 4d6f86c0..99b937a1 100644
--- a/docs/en/reference/frontmatter-config.md
+++ b/docs/en/reference/frontmatter-config.md
@@ -21,6 +21,19 @@ You can access frontmatter data via the `$frontmatter` global in Vue expressions
 {{ $frontmatter.title }}
 ```
 
+However, avoid using a Vue expression in this manner inside Markdown headings:
+
+```md
+---
+title: Docs with VitePress
+editLink: true
+---
+
+# {{ $frontmatter.title }}
+```
+
+The heading's anchor and accessibility attributes, as well as search index contents, are produced **before** Vue evaluates the expression, which will result in the string `frontmatter-title` being used in those places instead of the actual title.
+
 ## title
 
 - Type: `string`