facebook / facebook/docusaurus

RFC: new frontMatter to assign custom data to a doc

Đang mở
#6,923 11 bình luận 8 reaction 0 người được giao Xem trên GitHub
domain: content plugin proposal
Ngôn ngữ chính
TypeScript
Star
66.2k
Fork
10k
Merge trung bình
1 ngày 3 giờ
Pull request đã merge (30 ngày)
52

Mô tả

### 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/

image

---

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.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.