diff --git a/create/reusable-snippets.mdx b/create/reusable-snippets.mdx index ac9c368af..2d2f98214 100644 --- a/create/reusable-snippets.mdx +++ b/create/reusable-snippets.mdx @@ -1,7 +1,7 @@ --- 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 @@ -9,19 +9,38 @@ 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. - 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 `../`). -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. ### Default export diff --git a/customize/react-components.mdx b/customize/react-components.mdx index 318e9a49a..314774236 100644 --- a/customize/react-components.mdx +++ b/customize/react-components.mdx @@ -92,7 +92,7 @@ The counter renders as an interactive React component. ## 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 diff --git a/organize/settings.mdx b/organize/settings.mdx index d1e1d7dbb..324d96a26 100644 --- a/organize/settings.mdx +++ b/organize/settings.mdx @@ -347,6 +347,18 @@ This section contains the full reference for the `docs.json` file. + + 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. + + ### Structure