Skip to content
Closed
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
35 changes: 27 additions & 8 deletions create/reusable-snippets.mdx
Original file line number Diff line number Diff line change
@@ -1,27 +1,46 @@
---
title: "Reusable snippets"
description: "Create reusable snippets to maintain consistency across pages."
keywords: ["content snippets", "reusable content", "variables"]
keywords: ["content snippets", "reusable content", "variables", "snippets configuration"]
---

One of the core principles of software development is DRY (Don't Repeat

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.
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.

## Creating a custom snippet
## Snippet locations

By default, snippet files live in the `/snippets/` directory. You can also configure additional directories to store snippets using the `snippets` property in your `docs.json`.

**Pre-condition**: You must create your snippet file in the `snippets` directory in order for the import to work.
Any file in a snippet 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.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L16

Avoid using 'will'.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L16

In general, use active voice instead of passive voice ('be treated').

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L16

Use 'won't' instead of 'will not'.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L16

Avoid using 'will'.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L16

In general, use active voice instead of passive voice ('be rendered').

<Tip>
Snippets support both absolute imports (starting with `/snippets/`) and
Snippets support both absolute imports (starting with `/snippets/` or your custom path) and
relative imports (starting with `./` or `../`).
</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.
### Custom snippet directories

To organize snippets in custom locations, add the `snippets` property to your `docs.json` with an array of glob patterns. Patterns use [minimatch](https://github.com/isaacs/minimatch) syntax:

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

This configuration allows you to import snippets from the specified directories in addition to the default `/snippets/` folder:

```typescript destination-file.mdx
import Alert from '../components/Alert.mdx';
import Banner from '../shared/reusable/Banner.mdx';
import DefaultSnippet from '../snippets/my-snippet.mdx';
```

## Creating a custom snippet

**Pre-condition**: Your snippet file must be in the `/snippets/` directory or a [custom snippet directory](#custom-snippet-directories) you've configured.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L43

': Y' should be in lowercase.

### Default export

Expand Down Expand Up @@ -51,13 +70,13 @@

### Exporting with variables

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.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L73

In general, use active voice instead of passive voice ('be filled').

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

2. Import the snippet into your destination file with the variable. The property will fill in based on your specification.

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L79

Avoid using 'will'.

```typescript destination-file.mdx
---
Expand Down Expand Up @@ -98,7 +117,7 @@
Hello, my name is {myName} and I like {myObject.fruit}.
```

### JSX snippets

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L120

'JSX snippets' should use sentence-style capitalization.

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

Expand All @@ -113,8 +132,8 @@
```

<Note>
Important: When creating JSX snippets, use arrow function syntax (`=>`) rather

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L135

': W' should be in lowercase.
than function declarations. The `function` keyword is not supported in this

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

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

create/reusable-snippets.mdx#L136

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

Expand Down
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 directory. By default, this is the `/snippets/` folder, but you can [configure additional directories](/create/reusable-snippets#custom-snippet-directories) 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>
12 changes: 12 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 @@ -347,6 +347,18 @@
</Expandable>
</ResponseField>

<ResponseField name="snippets" type="array of string">
Additional directories to treat as snippet locations. Accepts an array of glob patterns using [minimatch](https://github.com/isaacs/minimatch) syntax. The `/snippets/` directory is always included by default.

```json
{
"snippets": ["components/**", "shared/reusable/**"]
}
```

See [Reusable snippets](/create/reusable-snippets) for more information.
</ResponseField>

### Structure

<ResponseField name="navbar" type="object">
Expand Down Expand Up @@ -550,7 +562,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 565 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L565

In general, use active voice instead of passive voice ('is expanded').
</ResponseField>
</Expandable>
</ResponseField>
Expand All @@ -560,7 +572,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 575 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L575

Avoid using 'will'.
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -638,7 +650,7 @@
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 653 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L653

Use parentheses judiciously.
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -672,7 +684,7 @@
</Expandable>
</ResponseField>

### API Configurations

Check warning on line 687 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L687

'API Configurations' should use sentence-style capitalization.

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

### SEO and search

Check warning on line 797 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L797

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

Check warning on line 797 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L797

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

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

Check warning on line 800 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L800

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

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