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 (<... />);
}

GitHub

View Github