Fragments, also known as content fragments, are powerful tools that allow you to incorporate content from other pages into your documentation. By creating an MDX file and using the generic directives syntax :fragment{src="path-to-fragment"}, you can easily render the fragment in another file, providing modularity and reusability to your content.

Fragments offer various use cases, such as:

Consistent Content: Use fragments to maintain consistent content across multiple pages. For instance, if you have a table or a tile that appears on multiple pages, you can create a fragment for it and include it in all relevant files. This ensures that any updates made to the fragment automatically reflect across the entire documentation.

Reusable Components: Fragments enable the creation of reusable components or sections. You can define a complex or commonly used section once and then include it in multiple pages as needed. This approach saves time and effort, as you only need to update the fragment file to propagate changes throughout your documentation.

Modular Documentation: With fragments, you can break down your documentation into smaller, manageable pieces. Each fragment represents a specific topic or section, allowing you to organize and structure your content more efficiently. This modular approach simplifies maintenance and makes it easier to navigate and update your documentation.

Firstly, enable the Fragment Plugin by adding the following to your plugins in mosaic.config.mjs.

To include a fragment in your content, follow these steps:

Create an MDX file for the fragment you want to reuse. Remember to set the sidebar property of your fragment's frontmatter to exclude: true if you don't want the fragment to appear in the vertical navigation menu.

In the target file where you want to include the fragment, use the remark directive syntax :fragment{src="path-to-fragment"}.

This is the contents of a fragment located at ../fragments/content-fragment.mdx:

The below code snippet will render the content from the content-fragment.mdx file in your target file:

Example output:

This is an example fragment of markdown content, being pulled from ../fragments/content-fragment.mdx.

Here is another example, where the fragment files each contain a <Tile> component.

The above code will render the content from tile-a.mdx and tile-b.mdx files, demonstrated below: