How snippets work
Snippets are any.mdx, .md, .js, .jsx, or .tsx files imported into another file. You can place snippet files anywhere in your project. Your site loads every .js file in your project as a custom script on every page, so .js snippets should only export data, not run code.
In Markdown page views, a <Snippet> tag is replaced by the snippet file, with docs.json variables filled in. The inserted content converts to Markdown along with the rest of the page.
When you import a snippet into another file, the snippet only appears where you import it and does not render as a standalone page. Any file in the /snippets/ folder is always a snippet even if it is not imported into another file.
Create snippets
Create a file with the content you want to reuse. Snippets can contain all content types supported by Mintlify and they can import other snippets. See Nested snippets for where to declare imports when nesting.Import snippets into pages
Import snippets into pages using either an absolute or relative path.- Absolute imports: Start with
/for imports from the root of your project. - Relative imports: Use
./or../to import snippets relative to the current file’s location.
MySnippet. MDX treats lowercase tags such as <mySnippet /> as literal HTML or custom element names rather than references to imported snippets.
Import text
Add content to your snippet file
Import the snippet into your destination file
Nested snippets
Snippets can import other snippets. Declare the import in the snippet file that uses the nested snippet, not in the page that imports the parent snippet. Each file resolves its own imports. Imports declared on a page do not apply to the snippets that the page imports. A nested snippet that relies on a page-level import may render as empty content.Import the nested snippet in the parent snippet file
Import only the parent snippet in your destination file
Import variables
Reference variables from a snippet in a page.Export variables from a snippet file
Import the snippet from your destination file and use the variable
{myName} and inline expressions like {1 + 1}. Their values do not appear in a page’s initial HTML or in offline exports, so crawlers, LLMs, and other tools that do not run JavaScript see the surrounding text without them. Write values as plain text if they must be visible in those situations.Import snippets with variables
Use variables to pass data to a snippet when you import it.Add variables to your snippet
{word}.Import the snippet into your destination file with the variable
Import React components
Create a snippet with a JSX component
=>) rather than function declarations. The function keyword is not supported in snippets.Import the snippet
Use global variables
Global variables replace short values, such as product names or version numbers, everywhere they appear in your content. Define variables in thevariables object of your docs.json.
{{variableName}} in any page or snippet, including inside code blocks.
title and description, so write those values as plain text.
Use camelCase names such as productName. The mint broken-links command parses pages before it replaces variables, so it reports a parse error for each page that uses a variable name with a hyphen.
To keep variables in their own file, point the variables key to a JSON file with $ref.
Use different values for the same content
Each variable has one value for the whole site. To give the same text a different value on different pages, use a snippet with props instead. To publish the same content as two sites with different values, such as a white-label version of your docs, create a separate site for each version. Each site’sdocs.json defines its own values.
Render content from structured data
Keep data such as a list of SDK components, a support matrix, or a set of plans in one snippet and render it on multiple pages. When you modify the data, every table, list, or card built from it updates. Store the data as a plain JSON object in a.js snippet with a named export. Then write a .jsx snippet that turns the data into markup.
.mdx, .md, .js, .jsx, or .tsx files. You cannot import a .json or .yaml file directly. Keep the data in a .js snippet, or generate one from your JSON or YAML source.Export the data from a snippet
Create a snippet that renders the data
map() and return HTML elements or Mintlify components.Import both snippets and pass the data as a property
Generate snippets and pages from JSON or YAML
If you store data in a JSON or YAML file, generate snippets from that source data. Use a script to write the data snippet with one page per entry and create the matching navigation group. Run the script in CI whenever the source file changes and commit the result.Write the generator
sdk-components.yaml, writes the snippet from the previous example, creates a page for each component, and replaces the pages of the navigation group named “Components” in docs.json.parse() with JSON.parse() and skip the yaml dependency. Running the script twice produces identical files, so it is safe to run on every push.Run it in a GitHub Action
GITHUB_TOKEN does not trigger other workflows when it pushes, so the job cannot loop. Mintlify deploys the push like any other commit.