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.

Release Version
License

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