Ability to expose extra docs data to existing pages (ex: expose frontMatter in tags pages)

[bartekwitczak]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

I want to expose more data from docs inside auto-generated tags pages (DocTagDocListPage).

Currently, there are only few things exposed ( docusaurus/packages/docusaurus-plugin-content-docs/src/props.ts ):

• id
• title
• description
• permalink

Generated tags pages are simple. I would like to improve them a lot by using more data from docs like front matter, especially since I've got a lot of custom front matter attributes.
For now, modifying & extending tags pages is very limited due to limited info.

Since those pages are generated outside of DocProviders, i didn't find a way to fetch more data otherwise that modify whole plugin workflow ( probably modifying contentLoaded function )

Moreover, I don't understand why currently only those 4 fields are exposed for tags pages.

Self-service

• I'd be willing to do some initial work on this proposal myself.

[slorber]

Since those pages are generated outside of DocProviders, i didn't find a way to fetch more data otherwise that modify whole plugin workflow ( probably modifying contentLoaded function )

You can't query the data you want here with our hooks because that data is simply not available on these pages

Moreover, I don't understand why currently only those 4 fields are exposed for tags pages.

We don't expose more data because we don't render more data. If we exposed more data but did not render that data by default (for example the frontmatter) this would mean that all sites having tags pages would have larger data bundle sizes which decreases page performance.

To not penalize the whole Docusaurus community, the exposure of extra data on these pages must be "opt-in". Ie we should give you the ability to define which data you need yourself, instead of adding a lot of data and expecting you to eventually use it.

---

For now the only way is indeed to modify the contentLoaded lifecycle of the page plugin. And we don't have any great API to extend a plugin for now (tracked in #4138), nor any API to make it easy to inject this extra data.

The way I see it in the future is that we would use React Server Components at build time, that would pick the appropriate data from a big DB object and inject that into your tag pages. And you would be able to swizzle those RSCs to add more data if you need, or create your own RSCs to query the DB.

Track RSC at #9089

Hope this makes sense.

Let's keep this issue open and make it more general to track progress on these ideas.

[bartekwitczak]

Hey @slorber, thanks for your response 🙏

Could you elaborate more on the performance ( bundle size)? I didn't get deep into internals & probably don't understand how site is build.

Does it mean that exposing data through creating JSON file:

const tagPropPath = await actions.createData(
  `${docuHash(`tag-${tag.permalink}`)}.json`,
  JSON.stringify(tagProps, null, 2),
);

is going to transfer everything to client with JS?

Definitely, React Server components would help with that, since nothing would be exposed to client apart from HTML.

[slorber]

is going to transfer everything to client with JS?

Yes, this data is added to js files that should be loaded before we start hydrating React on the page.

Adding more data in these bundles means it delays the React hydration process and reduce the lighthouse / CWV / perf score of the page. If we add data here but never display it, everybody pay the perf price for nothing.