Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 110 additions & 82 deletions create/reusable-snippets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,129 +4,157 @@
keywords: ["content snippets", "reusable content", "variables"]
---

One of the core principles of software development is DRY (Don't Repeat
Yourself), which applies to documentation as
well. If you find yourself repeating the same content in multiple places, you
should create a custom snippet to keep your content in sync.
One of the core principles of software development is DRY (Don't Repeat Yourself), which applies to documentation too. If you find yourself repeating the same content in multiple places, create a custom snippet for that content. Snippets contain content that you can import into other files to reuse. You control where the snippet appears on a page. If you ever need to update the content, you only need to edit the snippet rather than every file where the snippet is used.

Check warning on line 7 in create/reusable-snippets.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L7

Spell out 'DRY', if it's unfamiliar to the audience.

Check warning on line 7 in create/reusable-snippets.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L7

Use parentheses judiciously.

## Creating a custom snippet
Snippets do not render as standalone pages. You must import them into other files.

Check warning on line 9 in create/reusable-snippets.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L9

Use 'don't' instead of 'do not'.

**Pre-condition**: You must create your snippet file in the `snippets` directory in order for the import to work.
## Configure snippet folders

By default, any file in a folder named `snippets` is treated as a snippet. You can configure additional custom folders to contain snippets with the `snippets` field in your `docs.json`.

Add [glob patterns](https://code.visualstudio.com/docs/editor/glob-patterns) to the `snippets` array in `docs.json` to specify which folders contain snippets.

```json docs.json
{
"snippets": [
"components/**",
"shared/reusable/**",
"shared/common-component.mdx"
]
}
```

## Create snippets

Create a file in a snippet folder with the content you want to reuse. Snippets can contain all content types supported by Mintlify and they can import other snippets.

## Import snippets into pages

To use snippets, import them into pages using either an absolute or relative path.

- **Absolute imports**: Start with `/snippets/` or your custom snippet location for imports from the root of your project.
- **Relative imports**: Use `./` or `../` to import snippets relative to the current file's location.

<Tip>
Snippets support both absolute imports (starting with `/snippets/`) and
relative imports (starting with `./` or `../`).
Relative imports enable IDE navigation. Press <kbd>CMD</kbd> and click a snippet name in your editor to jump directly to the snippet definition.
</Tip>

Any page in the `snippets` directory will be treated as a snippet and will not
be rendered into a standalone page. If you want to create a standalone page
from the snippet, import the snippet into another file and call it as a
component.
### Import text

### Default export
1. Add content to your snippet file that you want to reuse.

1. Add content to your snippet file that you want to re-use.
```mdx snippets/my-snippet.mdx
Hello world! This is my content I want to reuse across pages.
```

```typescript snippets/my-snippet.mdx
Hello world! This is my content I want to reuse across pages.
```
2. Import the snippet into your destination file using either an absolute or relative path.

2. Import the snippet into your destination file.
<CodeGroup>

```typescript destination-file.mdx
---
title: My title
description: My Description
---
```mdx Absolute import
---
title: "An example page"
description: "This is an example page that imports a snippet."
---

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

## Header
The snippet content displays beneath this sentence.

Lorem impsum dolor sit amet.
<MySnippet/>
```

<MySnippet/>
```mdx Relative import
---
title: "An example page"
description: "This is an example page that imports a snippet."
---

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

```
The snippet content displays beneath this sentence.

### Exporting with variables
<MySnippet/>
```

1. Optionally, you can add variables that can be filled in via props when you import the snippet. In this example, our variable is word.
</CodeGroup>

```typescript snippets/my-snippet.mdx
My keyword of the day is {word}.
```
### Import variables

2. Import the snippet into your destination file with the variable. The property will fill in based on your specification.
Reference variables from a snippet in a page.

```typescript destination-file.mdx
---
title: My title
description: My Description
---
1. Export variables from a snippet file.

import MySnippet from '/snippets/path/to/my-snippet.mdx';
```mdx snippets/custom-variables.mdx
export const myName = "Ronan";

## Header
export const myObject = { fruit: "strawberries" };
```

Lorem impsum dolor sit amet.
2. Import the snippet from your destination file and use the variable.

<MySnippet word="bananas" />
```mdx destination-file.mdx
---
title: "An example page"
description: "This is an example page that imports a snippet with variables."
---

```
import { myName, myObject } from '/snippets/custom-variables.mdx';

### Reusable variables
Hello, my name is {myName} and I like {myObject.fruit}.
```

1. Export a variable from your snippet file:
### Import snippets with variables

```typescript snippets/path/to/custom-variables.mdx
export const myName = "my name";
Use variables to pass data to a snippet when you import it.

export const myObject = { fruit: "strawberries" };
```
1. Add variables to your snippet and pass in properties when you import it. In this example, the variable is `{word}`.

2. Import the snippet from your destination file and use the variable:
```mdx snippets/my-snippet.mdx
My keyword of the day is {word}.
```

```typescript destination-file.mdx
---
title: My title
description: My Description
---
2. Import the snippet into your destination file with the variable. The passed property replaces the variable in the snippet definition.

import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
```mdx destination-file.mdx
---
title: "An example page"
description: "This is an example page that imports a snippet with a variable."
---

Hello, my name is {myName} and I like {myObject.fruit}.
```
import MySnippet from '/snippets/my-snippet.mdx';

### JSX snippets
<MySnippet word="bananas" />

1. Export a JSX component from your snippet file. (See [React components](/customize/react-components) for more information):
```

```js icon=square-js snippets/my-jsx-snippet.jsx
export const MyJSXSnippet = () => {
return (
<div>
<h1>Hello, world!</h1>
</div>
);
};
```
### Import React components

1. Create a snippet with a JSX component. See [React components](/customize/react-components) for more information.

```js snippets/my-jsx-snippet.jsx
export const MyJSXSnippet = () => {
return (
<div>
<h1>Hello, world!</h1>
</div>
);
};
```

<Note>
Important: When creating JSX snippets, use arrow function syntax (`=>`) rather
than function declarations. The `function` keyword is not supported in this
context.
When creating JSX snippets, use arrow function syntax (`=>`) rather than function declarations. The `function` keyword is not supported in snippets.

Check warning on line 146 in create/reusable-snippets.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L146

Use 'isn't' instead of 'is not'.
</Note>

2. Import the snippet from your destination file and use the component:
2. Import the snippet.

```typescript destination-file.mdx
---
title: My title
description: My Description
---
```mdx destination-file.mdx
---
title: "An example page"
description: "This is an example page that imports a snippet with a React component."
---

import { MyJSXSnippet } from '/snippets/my-jsx-snippet.jsx';
import { MyJSXSnippet } from '/snippets/my-jsx-snippet.jsx';

<MyJSXSnippet />
```
<MyJSXSnippet />
```
2 changes: 1 addition & 1 deletion customize/react-components.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@

## Importing components

To import React components in your MDX files, the component files must be located in the `snippets` folder. You can then import them into any MDX page in your documentation. Learn more about [reusable snippets](/create/reusable-snippets).
To import React components in your MDX files, the component files must be located in a snippet folder. By default, this is the `/snippets/` folder. You can [configure additional directories](/create/reusable-snippets#configure-snippet-folders) to contain snippets in your `docs.json`. Learn more about [reusable snippets](/create/reusable-snippets).

### Example

Expand Down Expand Up @@ -236,9 +236,9 @@
- **Accessibility**: Ensure dynamic content changes are announced to screen readers.
</Accordion>
<Accordion title="Performance best practices">
- **Optimize dependency arrays**: Include only necessary dependencies in your `useEffect` dependency arrays.

Check warning on line 239 in customize/react-components.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/react-components.mdx#L239

': I' should be in lowercase.
- **Memoize complex calculations**: Use `useMemo` or `useCallback` for expensive operations.

Check warning on line 240 in customize/react-components.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/react-components.mdx#L240

': U' should be in lowercase.
- **Reduce re-renders**: Break large components into smaller ones to prevent cascading re-renders.

Check warning on line 241 in customize/react-components.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/react-components.mdx#L241

': B' should be in lowercase.
- **Lazy loading**: Consider lazy loading complex components to improve initial page load time.

Check warning on line 242 in customize/react-components.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

customize/react-components.mdx#L242

': C' should be in lowercase.
</Accordion>
</AccordionGroup>
10 changes: 10 additions & 0 deletions organize/settings.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@
</ResponseField>

<ResponseField name="colors" type="object" required>
The colors used in your documentation. Colors are applied differently across themes. If you only provide a primary color, it will be used for all color elements.

Check warning on line 53 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L53

Avoid using 'will'.

<Expandable title="Colors">
<ResponseField name="primary" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$" required>
Expand Down Expand Up @@ -115,7 +115,7 @@
Background image for your thumbnails. Can be a relative path or absolute URL.
</ResponseField>
<ResponseField name="fonts" type="object">
Font configuration for thumbnails. Only Google Fonts family names are supported.

Check warning on line 118 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L118

In general, use active voice instead of passive voice ('are supported').

<Expandable title="Fonts">
<ResponseField name="family" type="string" required>
Expand Down Expand Up @@ -550,7 +550,7 @@

<Expandable title="Interaction">
<ResponseField name="drilldown" type="boolean">
Control automatic navigation behavior when selecting navigation groups. Set to `true` to force navigation to the first page when a navigation group is expanded. Set to `false` to prevent navigation and only expand or collapse the group. Leave unset to use the theme's default behavior.

Check warning on line 553 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L553

In general, use active voice instead of passive voice ('is expanded').
</ResponseField>
</Expandable>
</ResponseField>
Expand All @@ -560,7 +560,7 @@

<Expandable title="Metadata">
<ResponseField name="timestamp" type="boolean">
Enable the last modified date on all pages. When enabled, all pages will display the date the content was last modified. Defaults to `false`.

Check warning on line 563 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L563

Avoid using 'will'.
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -638,11 +638,21 @@
Destination path to redirect to. Example: `/new-page`
</ResponseField>
<ResponseField name="permanent" type="boolean">
Whether to use a permanent redirect (301). Defaults to `true`.

Check warning on line 641 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L641

Use parentheses judiciously.
</ResponseField>
</Expandable>
</ResponseField>

<ResponseField name="snippets" type="array of strings">
Specify additional folders for reusable snippets using [glob patterns](https://code.visualstudio.com/docs/editor/glob-patterns). Any files in folders matching these patterns are snippets, in addition to the default `/snippets/` folder.

```json Example snippets configuration
{
"snippets": ["components/**", "shared/shared-file.mdx"]
}
```
</ResponseField>

<ResponseField name="contextual" type="object">
Contextual menu for AI-optimized content and integrations.

Expand Down Expand Up @@ -672,7 +682,7 @@
</Expandable>
</ResponseField>

### API Configurations

Check warning on line 685 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L685

'API Configurations' should use sentence-style capitalization.

<ResponseField name="api" type="object">
API documentation and interactive playground settings.
Expand Down Expand Up @@ -782,10 +792,10 @@
</Expandable>
</ResponseField>

### SEO and search

Check warning on line 795 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L795

Spell out 'SEO', if it's unfamiliar to the audience.

Check warning on line 795 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L795

'SEO and search' should use sentence-style capitalization.

<ResponseField name="seo" type="object">
SEO indexing configurations.

Check warning on line 798 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L798

Spell out 'SEO', if it's unfamiliar to the audience.

<Expandable title="Seo">
<ResponseField name="metatags" type="object">
Expand Down