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: #2840 (comment)

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

• Follow our Code of Conduct
• Read the docs.
• Read the Contributing Guidelines.
• 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 🙏🏻