From b2cc1e0d693ea5f17955516736e32c3c521c1826 Mon Sep 17 00:00:00 2001
From: T <6601329+cookesan@users.noreply.github.com>
Date: Sat, 27 Jun 2026 18:14:31 -0300
Subject: [PATCH] docs: clarify page headers config (#5233)

---
 docs/en/reference/runtime-api.md | 2 ++
 docs/en/reference/site-config.md | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/docs/en/reference/runtime-api.md b/docs/en/reference/runtime-api.md
index 95a74e72..b39e4dcd 100644
--- a/docs/en/reference/runtime-api.md
+++ b/docs/en/reference/runtime-api.md
@@ -62,6 +62,8 @@ interface PageData {
 }
 ```
 
+`page.headers` is populated only when [`markdown.headers`](./site-config#markdown) is enabled. Without that option, it remains an empty array. The default theme outline reads rendered headings from the page content, so it can still appear when `page.headers` is empty.
+
 **Example:**
 
 ```vue
diff --git a/docs/en/reference/site-config.md b/docs/en/reference/site-config.md
index 67fd0640..4c8c50e6 100644
--- a/docs/en/reference/site-config.md
+++ b/docs/en/reference/site-config.md
@@ -561,6 +561,8 @@ export default {
 
 Check the [type declaration and jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) for all the options available.
 
+Set `markdown.headers` to `true` or pass [`@mdit-vue/plugin-headers`](https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers) options to collect headings into [`useData().page.headers`](./runtime-api#usedata). This option is disabled by default.
+
 ### vite
 
 - Type: `import('vite').UserConfig`