RFC: new frontMatter to assign custom data to a doc

[slorber]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

For some documentation use-cases, it is convenient to be able to assign additional data to a doc

It should be possible to create fancy views/tables/aggregations of a set of documents based on those extra data and display those anywhere thanks to MDX.

---

This has been requested/discussed in #6302 (comment)

For example, @Danielku15 wants to display a table of a subset of the documents in a page of his documentation:

https://alphatab.net/docs/reference/settings/

---

When a doc is created, Docusaurus creates data for this doc in 3 places:

• Doc metadata: this contains every interesting data we have related to a docs (including all frontMatter). It can be heavier.
• Version metadata: this is shared between all the pages of a given docs version, and thus should remain relatively small.
• Global data: this is shared across the whole site page, and must stay as small as possible (so we only include id/path/sidebar here, see https://docusaurus.io/__docusaurus/debug/globalData)

For data shared between multiple pages, the smallest the better. For performance reasons, we can't pre-emptively add any doc data everywhere without penalizing the performance of all the pages.

---

My suggestion is to add 2 distinct frontMatter to give the ability to assign extra data to a doc on a case-by-case basis

global_custom_props: 
  a: b
  c: d
  e: ["f"]

version_custom_props: 
  x: {y: 1, z: 2}

This would allow each doc to enrich the predefined minimal version/global data that Docusaurus needs to be able to run.

These data would become available in the React components (swizzled theme components or MDX embedded) so that users can create more fancy experiences.

---

What if you want to inject data that is not convenient to declare through yaml/frontMatter?

I think the createFrontMatter() proposal #5568 (also frontMatterParser PR #5972) could handle that:

global_custom_props: 
  dataPath: ./data/docX_global.json

And the createFrontMatter callback would be responsible to transform the path to a JS object.

And if I want to inject data that already exists as frontMatter?

That would be a bit odd to have to do this to propagate doc title in global data

title: my title
global_custom_props: 
  title: my title

Similarly using something like to createFrontMatter would help to set up propagation of existing frontmatter like title into global data

Self-service

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

[Josh-Cena]

This is basically the same as #4492, correct?

[slorber]

That looks quite similar yes, with a more concrete proposal and flexible API?

@kaytwo @zhouzi any opinion on this: would it solve your use-cases?

[Danielku15]

Some remarks from my side on the proposal 😁

1. [Clarification] Each Page should still have it's own individual set of properties it can expose globally or within the same version. Very simplified:

// docs/api/PropertyA.mdx
version_custom_props:
  available_since: 1.3.0
// docs/api/PropertyB.mdx
version_custom_props: 
  available_since: 1.2.0 
// docs/guides/SomeGuide.mdx
export function AvailableSince({id}) { return useDocById(id).version_custom_props.available_since; }

PropertyA is available since version <AvailableSince id="docs/api/PropertyA" /> while PropertyB is only already available since <AvailableSince id="docs/api/PropertyB" />

// docs/guides/SomeGuide.mdx rendered 

PropertyA is available since version 1.3.0 while PropertyB is only already available since 1.2.0

I personally would have no use case where all pages are writing to the same global object and can potentially overwrite the values. It would make things complicated to handle.

2. [Clarification] Should we already try to define how we gonna access this data? It might influence the feature design, especially as you have performance concerns. 😉 From our earlier discussion I guess one way would be through useDocById() which would then have version_custom_props and global_custom_props members in the returned object? It might also be useful to access an overall object where the top level key is the docs id: { "docs/api/PropertyA": { /* same result as returned by getDocById? */ }, "docs/api/PropertyB": { ... } .

3. [Example Usage] The second feature I would like to achieve with this enhancement is to add rich cross reference tooltips as we can see them when hovering links here in GitHub. When I'm referencing any setting, method, property documented on a different page, I want to provide a corresponding badge which has a tooltip revealing a sneak-peek to the information of the other page. The tooltip will be filled with data from the new title, description and the new **_custom_props:

[zhouzi]

@kaytwo @zhouzi any opinion on this: would it solve your use-cases?

Actually my use case is closer to #4138 than #4492 so I don't think this new feature would help with that. But it definitely looks like what's described in #4492 👍

[Josh-Cena]

#4492 is recommended to be solved with #4138 because we'll likely not add such an option to propagate "arbitrary" front matter as globals. That sounds too prone to anti-patterns. This new custom_metadata front matter + createFrontMatter callback seems both more flexible and less "artificial"

[PoetaKodu]

I'm creating a "See also" section for C++ standard library symbols and could also make use of custom metadata. This would allow for the tables to be synchronized because right now we can either

• write each time everything ourselves
• access description metadata using useDocById from @docusaurus/theme-common

The first one creates a lot of redundancy in the site source and is time-consuming. The second option uses the webpage's description which is not exactly what we want. Consider this example. We want a std::string::operator[] page to reference std::string::at() method providing its description.

• std::string::at() page description (as seen from an external site):

  std::string::at() method reference - C++ Standard Library documentation

• std::string::at() symbol description (as seen from the "See also" section in std::string::operator[]):

  Returns a reference to the character at specified index, with bounds checking.

In my case, the page description and the description for a see also section differ.

Wrong result:

Site metadata: