facebook / facebook/docusaurus
RFC: new frontMatter to assign custom data to a doc
- Dominant language
- TypeScript
- Stars
- 66.2k
- Forks
- 10k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 52
Description
### Have you read the Contributing Guidelines on issues?
- [X] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-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 https://github.com/facebook/docusaurus/issues/6302#issuecomment-1056869348
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
```md
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 https://github.com/facebook/docusaurus/issues/5568 (also `frontMatterParser` PR https://github.com/facebook/docusaurus/pull/5972) could handle that:
```md
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
- [X] I'd be willing to do some initial work on this proposal myself.
Contributor guide
Assessment
This issue has not been assessed yet.