improve developer experience for default-empty 'headers' field in PageData

[indirectlylit]

Is your feature request related to a problem? Please describe.

page.headers as returned from useData was an empty array even though my document had headers defined. It took my some searching to understand that I needed to set the following config in order to populate it:

  markdown: {
    headers: true,
  },

This issue – where the user had the same confusion – helped me understand: https://github.com/vuejs/vitepress/issues/2840#issuecomment-1691067613

Describe the solution you'd like

Two things might help

1. add documentation which connects https://vitepress.dev/reference/runtime-api#usedata to https://vitepress.dev/reference/site-config
2. make headers optional, and don't include it when not enabled ([] vs undefined)

Describe alternatives you've considered

possibly enable headers by default

Additional context

No response

Validations

• [X] Follow our Code of Conduct
• [X] Read the docs.
• [X] Read the Contributing Guidelines.
• [X] Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[zernonia]

Agree! I spend many hours looking for why page.headers are empty, and finally came across this ticket. Would really appreciate if this was documented 🙏🏻

[lepture]

Thanks for the tips. It took me a night to debug this issue.

I didn't change my config.ts file, it is weird, without

markdown: {
    headers: true,
  },

the default theme works well.