facebook / facebook/docusaurus

Proposal: enable option to propagate arbitrary frontmatter data in globals

Open
#4,492 14 comments 1 reaction 0 assignees View on GitHub
domain: content plugin feature
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

## 🚀 Feature

Expose markdown frontmatter in page globals.

### Have you read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md#reporting-new-issues)?

Yes

## Motivation

I'd like to programmatically generate docs/pages based on custom metadata stored in the frontmatter of my docs. In my use case, I'm building a course website, where the docs are the descriptions of homeworks, labs, exams, etc, and I'd like to create a "calendar" page that reads release and due date metadata from the frontmatter of each of those pages. As of right now, only `id`, `path`, and `sidebar` are set in the plugin globals.

## Pitch

While this is a very specific use case, I've typically seen frontmatter used in this way in other static site generators to create derivative pages that incorporate some or all of the important metadata from some subset of other pages.

I tried to implement something similar to this both using [this approach](https://github.com/facebook/docusaurus/issues/4431) as well as [a standalone plugin](https://github.com/kaytwo/docusaurus-plugin-frontmatters) that I wrote for this purpose (trying both `setGlobalData` and `createData`), but the issue is that the functionality is too tightly tied to the docs plugin itself to be easily factored out (and I couldn't figure out how to swizzle this part of `@docusaurus/plugin-content-docs`).

## Implementation

The frontmatter can be propagated with this commit: . I understand that this will increase the size of the globals which should be avoided, however this option could probably be gated behind a config option by replacing [this line](https://github.com/kaytwo/docusaurus/blob/ff408e1b4a0c5ca31ad00c0566cc1f287b662e72/packages/docusaurus-plugin-content-docs/src/docs.ts#L222) in `docs.ts` with:

```ts
frontMatter : options.includeFrontmatter ? frontMatter : undefined
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.