docusaurus-theme-frontmatter
This package enhances the Docusaurus classic theme by exposing the docs, blog, and pages front matter to the following components and their children:
Furthermore, this allows you to define and access custom front matter.
Install
yarn add docusaurus-theme-frontmatter
Then, include the plugin in your docusaurus.config.js file.
// docusaurus.config.js
module.exports = {
...
+ themes: ['docusaurus-theme-frontmatter'],
...
}
TypeScript support
To enable TypeScript support, the TypeScript configuration should be updated to add the docusaurus-theme-frontmatter type definitions. This can be done in the tsconfig.json file:
{
"extends": "@tsconfig/docusaurus/tsconfig.json",
"compilerOptions": {
...
+ "types": ["docusaurus-theme-frontmatter"]
}
}
How to use
The useFrontMatter() hook is made available to any of your components through the @theme/useFrontMatter import. For example, you might have a component that creates a gallery of images.
---
title: Miniature fairy doors of NYC
hide_table_of_contents: true
gallery:
- /images/117-first-avenue.jpg
- /images/lower-east-side.jpg
- /images/my-guinness.jpg
- /images/hundred-years.jpg
---
import Galley from '@theme/Galley';
<Galley />
import React from 'react';
import ImageGallery from 'react-image-gallery';
import useFrontMatter from '@theme/useFrontMatter';
export default function GalleyComponent () {
const { gallery } = useFrontMatter();
if (Array.isArray(gallery)) {
const images = gallery.map((image) => ({
original: image
}));
return <ImageGallery items={images} />;
}
return null;
}
Public API
useFrontMatter<T extends FrontMatter>()
Returns the front matter for the current context.
import useFrontMatter from '@theme/useFrontMatter';
interface CustomFrontMatter {
gallery?: string[];
}
const MyComponent = () => {
const { gallery } = useFrontMatter<CustomFrontMatter>();
return (<... />);
}
Context
The current front matter context.
Generally, this is something to be left alone and operates behind the scenes. This is how it is used to enhance DocItem scaffolding the hook:
import { Context } from '@theme/useFrontMatter';
import DocItem from '@theme-init/DocItem';
import React from 'react';
export default (props) => <Context.Provider value={props.content.frontMatter}>
<DocItem {...props} />
</Context.Provider>;
FrontMatter, DocItemFrontMatter, BlogPostItemFrontMatter, MDXPageFrontMatter
These types are provided to assist in describing the values returned by the useFrontMatter() hook.
import useFrontMatter from '@theme/useFrontMatter';
import type { DocItemFrontMatter } from '@theme/useFrontMatter';
const MyComponent = () => {
const { id, title, keywords } = useFrontMatter<DocItemFrontMatter>();
return (<... />);
}
75.8k Jan 5, 2023
10.6k Jan 7, 2023
291 Oct 13, 2022
48 Apr 17, 2022
1 Oct 28, 2021
1.2k Jan 6, 2023
459 Nov 12, 2022
8 Dec 6, 2021
3 Mar 20, 2022
492 Aug 15, 2022
42 Dec 28, 2022
37 Nov 22, 2022
44 Nov 13, 2022
4 Jul 19, 2021
13 Apr 26, 2022
50 Dec 1, 2022
11k Dec 31, 2022
16.5k Jan 6, 2023