Frontmatter

Frontmatter, also known as page metadata, is a powerful feature that allows easy configuration of a page and Mosaic site components e.g. the sidebar.

Frontmatter is written in yaml syntax and is found at the top of a page between 2 sets of 3 dashes: ---.

Example page yaml

---
title: Page Title
layout: DetailTechnical
sidebar:
  priority: 4
---

// frontmatter is closed and now comes page content
# Page Title

This is some content.

Accessing Frontmatter in content

With the syntax below it is possible to directly reference frontmatter inside content using curly brackets and the meta object.

You can think of meta as a JSON object that holds all the frontmatter of a page and when the Mosaic RefPlugin encounters the curly brackets then the value in the frontmatter will be resolved.

{meta.title}
{meta.description}
{meta.someValueYouHaveAddedToTheFrontmatter}

This is very common to see Mosaic pages that reference the title as shown below:

---
title: Title
---

# {meta.title}

Plugins & Frontmatter

Mosaic plugins can also embed their output into page frontmatter in 2 different ways:

  • a property is directly added to the page object
  • a JSON file is generated and referenced using a ref

Adding a property to the page

A plugin can add a property to a page simply by extending the page object it receives in the $afterSource lifecycle event:

async function $afterSource(pages) {
  for (const page of pages) {
    page.newProperty = 'Hello'
  }
  return pages;
}

You could use this property in the page content using {meta.newProperty}

JSON File

Let's take a look at the SharedConfigPlugin.

The purpose of this plugin is to crawl the page hierarchy to find the closest sharedConfig found in any parent page's frontmatter.

  • Finds all index pages among the source docs
  • Deserialises those pages so it can read the frontmatter and content of the page
  • If a property called sharedConfig in the page frontmatter is found a new file named shared-config.json is created
  • Adds a ref named config to the shared config file that points to the shared config of the index page
import type { Page, Plugin as PluginType } from '@jpmorganchase/mosaic-types';
import { flatten } from 'lodash-es';
import path from 'path';

function createFileGlob(url, pageExtensions) {
if (pageExtensions.length === 1) {
return `${url}${pageExtensions[0]}`;
}
return `${url}{${pageExtensions.join(',')}}`;
}

interface SharedConfigPluginPage extends Page {
sharedConfig?: string;
}

interface SharedConfigPluginOptions {
filename: string;
}

const SharedConfigPlugin: PluginType<SharedConfigPluginPage, SharedConfigPluginOptions> = {
async $beforeSend(
    mutableFilesystem,
    { config, serialiser, ignorePages, pageExtensions },
    options
  ) {
    const pagePaths = await mutableFilesystem.promises.glob(
      createFileGlob('**/index', pageExtensions),
      {
        ignore: [options.filename, ...flatten(ignorePages.map(ignore => [ignore, `**/${ignore}`]))],
cwd: '/'
}
);

    for (const pagePath of pagePaths) {
      const sharedConfigFile = path.join(path.dirname(String(pagePath)), options.filename);

      const page = await serialiser.deserialise(
        String(pagePath),
        await mutableFilesystem.promises.readFile(String(pagePath))
      );
      if (page.sharedConfig) {
        config.setRef(sharedConfigFile, ['config', '$ref'], `${String(pagePath)}#/sharedConfig`);
        await mutableFilesystem.promises.writeFile(sharedConfigFile, '{}');
      } else {
        const baseDir = path.posix.resolve(path.dirname(String(pagePath)), '../');
        config.setAliases(path.join(baseDir, options.filename), [sharedConfigFile]);
      }
    }

}
};

export default SharedConfigPlugin;
Mosaic BETA

Coming soon