Reusable snippets

One of the core principles of software development is DRY (Don’t Repeat Yourself). This applies to documentation too. If you find yourself repeating the same content across multiple pages, create a reusable snippet to keep everything in sync.

Creating a snippet

Pre-condition: Snippet files must live in the snippets directory.

Files in the snippets directory are treated as components, not standalone pages. To render a snippet as a page, import it into an MDX file outside of snippets.

Default export

Create a snippet with the content you want to reuse. You can accept props as variables.

snippets/my-snippet.mdx

Hello world! This is reusable content. The keyword is {word}.

Snippet files must be inside the snippets directory for imports to resolve.

Import and use the snippet in any page:

destination-file.mdx

---
title: My page
description: Example page
---

import MySnippet from '/snippets/path/to/my-snippet.mdx';

## Section

<MySnippet word="bananas" />

Reusable variables

Export variables from a snippet:

snippets/variables.mdx

export const appName = 'ecge';
export const config = { maxRetries: 3 };

Import and use them:

destination-file.mdx

import { appName, config } from '/snippets/variables.mdx';

Welcome to {appName}. Max retries: {config.maxRetries}.

Reusable components

Export a component as an arrow function:

snippets/custom-component.mdx

export const Alert = ({ title }) => (
  <div>
    <h3>{title}</h3>
    <p>This is a reusable alert component.</p>
  </div>
);

MDX does not compile inside arrow function bodies. Use HTML syntax within exported components.

Import and use it:

destination-file.mdx

import { Alert } from '/snippets/custom-component.mdx';

<Alert title="Heads up" />

Images and embeds

Getting started

Platform

Building

Reusable snippets

Creating a snippet

Default export

Reusable variables

Reusable components

​Creating a snippet

​Default export

​Reusable variables

​Reusable components

Creating a snippet

Default export

Reusable variables

Reusable components