Snippets v3 docs (#2363)

* add snippets prop

* update path info in React page

* update snippets page

* reviewer feedback

Author: ethanpalm

create/reusable-snippets.mdx

@@ -4,129 +4,157 @@ description: "Create reusable snippets to maintain consistency across pages."
 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.
 
-## Creating a custom snippet
+Snippets do not render as standalone pages. You must import them into other files.
 
-**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.
 </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 />
+  ```

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

organize/settings.mdx

@@ -643,6 +643,16 @@ This section contains the full reference for the `docs.json` file.
   </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.