Refs are a very powerful feature of Mosaic documents that use JSON References to reference a property from the page frontmatter or frontmatter of other pages.

The key concept is that of a JSON pointer which takes the form A#B where:

• A is the relative path from the current schema to a target schema. If A is empty, the reference is to a type or property in the same schema, an in-schema reference. Otherwise, the reference is to a different schema, a cross-schema reference.
• B is the complete path from the root of the schema to a type or property in the schema. If # in not included or B is empty, the reference is to an entire schema.

To translate this for our purposes:

• A is the relative path to a file in the filesystem.
• B is the path to a property in the frontmatter of the file.

It's probably better explained with examples...

It is possible to reference a page's own frontmatter to avoid duplication:

This page you are reading right now has a sidebar priority of 3.

The value of data.sidebarPriority comes from sidebar.priority in the frontmatter.

It is possible to reference frontmatter of other pages. Again this helps avoid duplication but the real power is using refs to build the data model. See advanced for more information.

The index page of the Author section has this frontmatter:

This page you are currently looking at is referencing the data.exampleRefData in it's frontmatter like this:

I can then use the data and embed it in this page like this:

And here it is: Hello from Author page

You have had a taste of the power and want to know more? OK, lets reference and then list out all the mosaic modes:

• active
• snapshot-file
• snapshot-s3

The Modes index page has this frontmatter:

The ref here is essentially using a wildcard (the *) to grab the mode property from the frontmatter of every page in the modes folder.

We can reference that data just like before:

With the code below, the referenced data can be embedded in a page.

You can use Mosaic components with referenced data as well. Below we are using the Tiles and TileLink components.

Mosaic plugins can create new refs, create new global refs and see existing refs created by the page or other plugins. This is achieved using a special config property available in the plugin helpers.

Use the config.setRef function from the helpers provided to plugin lifecycle events. You need to provide

• The file/fullpath to write the ref to
• The path to the ptoperty where the ref will be applied
• The value of the ref, which can use wildcards

For example, the following would add a property to pages named titles. The value is the title of all pages in the same directory as the current page

To view refs that already exist you can use config.data.refs. For example to see all refs for a page:

Global refs are similar to regular refs except they do not pre-resolve. This means they are resolved when the referenced file is read and the global mosaic filesystem, made up of multiple sources, is used rather than the filesystem of a single source.