From 1f8888b70c222622a71b8c87bb4cb091b5bc0efc Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:39:42 -0700 Subject: [PATCH 01/29] Update Quickstart page for style and clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Improve readability and flow - Make language more concise and consistent - Remove unnecessary periods from numbered lists - Clarify instructions and terminology 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- quickstart.mdx | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index dea8714e5..84d3b3036 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -4,9 +4,9 @@ description: "Deploy your documentation in minutes" icon: "rocket" --- -This quickstart guide shows you how to set up and deploy your documentation site in minutes. +This quickstart guide shows you how to set up and deploy your documentation site in minutes using Mintlify. -After you complete this guide, you will have a live documentation site ready to customize and expand. +After completing this guide, you'll have a live documentation site ready to customize and expand. @@ -16,7 +16,7 @@ After you complete this guide, you will have a live documentation site ready to ## Getting Started -After you complete the onboarding process, your documentation site will automatically deploy to a unique URL with this format: +After completing the onboarding process, your documentation site automatically deploys to a unique URL with this format: ``` https://.mintlify.app @@ -29,18 +29,18 @@ Find your URL on the Overview page of your [dashboard](https://dashboard.mintlif Mintlify Domain -This URL becomes available immediately and updates when you make changes to your documentation. Use this URL for testing and sharing with your team during development. +This URL is available immediately and updates automatically when you make changes to your documentation. Use this URL for testing and sharing with your team during development. ### Install the GitHub App Mintlify provides a GitHub App that automates deployment when you push changes to your repository. -Install the GitHub App by following the instructions from the onboarding checklist or from your dashboard. +Install the GitHub App by following the instructions from the onboarding checklist or your dashboard. -1. Navigate to **Settings** in your Mintlify dashboard. -2. Select **GitHub App** from the sidebar. -3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page. -4. Select the organization or user account where you want to install the app. Then select the repositories that you want to connect. +1. Navigate to **Settings** in your Mintlify dashboard +2. Select **GitHub App** from the sidebar +3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page +4. Select the organization or user account where you want to install the app, then select the repositories you want to connect GitHub App Installation @@ -53,9 +53,9 @@ Install the GitHub App by following the instructions from the onboarding checkli ### Authorize your GitHub Account -1. Navigate to **Settings** in your Mintlify dashboard. -2. Select **My Profile** from the sidebar. -3. Select **Authorize GitHub account**. This opens a new tab to the GitHub authorization page. +1. Navigate to **Settings** in your Mintlify dashboard +2. Select **My Profile** from the sidebar +3. Select **Authorize GitHub account**. This opens a new tab to the GitHub authorization page An admin for your GitHub organization may need to authorize your account depending on your organization settings. @@ -105,9 +105,9 @@ pnpm add -g mint ### Edit the Documentation -After you set up your environment, you can start editing your documentation files. For example, update the title of the introduction page: +After setting up your environment, you can start editing your documentation files. For example, update the title of the introduction page: -Open your repository created during onboarding, find the `index.mdx` file, and find the top of the file: +Open your repository created during onboarding, find the `index.mdx` file, and locate the top of the file: ```mdx index.mdx --- @@ -142,11 +142,11 @@ Your preview will be available at `localhost:3000`. ### Push the Changes -When you are ready to publish your changes, push the changes to your repository. +When you're ready to publish your changes, push them to your repository. Mintlify automatically detects the changes, builds your documentation, and deploys the updates to your site. Monitor the deployment status in your GitHub repository commit history or the [dashboard](https://dashboard.mintlify.com). -After the deployment is complete, your latest update will be available at `.mintlify.app`. +After deployment completes, your latest update will be available at `.mintlify.app`. Optionally, skip the web editor workflow and jump to adding a custom domain. @@ -189,26 +189,26 @@ Then, in the editor, update the title field to "Hello World". ### Publish Your Changes -When you are satisfied with your edits, select the **Publish** button in the top-right corner. Your changes are immediately deployed to your documentation site. +When you're satisfied with your edits, select the **Publish** button in the top-right corner. Your changes are immediately deployed to your documentation site. Use branches to preview and review changes through pull requests before deploying to your live site. -For more details about using the web editor, including using branches and pull request to collaborate and preview changes, see our [web editor documentation](/editor). +For more details about using the web editor, including using branches and pull requests to collaborate and preview changes, see our [web editor documentation](/editor). ## Adding a Custom Domain While your `.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation. -To add a custom domain, go to `Settings` > `Custom Domain` from the dashboard. +To add a custom domain, navigate to `Settings` > `Custom Domain` from the dashboard. Custom Domain Custom Domain -Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS (Domain Name System) settings with your domain provider. +Enter your domain (for example, `docs.yourcompany.com`) and follow the provided instructions to configure DNS settings with your domain provider. | Record Type | Name | Value | TTL | From 81ad53f95665d15b1273c5843adef2da193cbbed Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:40:22 -0700 Subject: [PATCH 02/29] Update Expandables component page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add clear introduction explaining the component's purpose - Remove unnecessary period from description - Improve formatting consistency for boolean values - Enhance clarity in prop descriptions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- components/expandables.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/components/expandables.mdx b/components/expandables.mdx index 431048ca0..f5fe1e5e0 100644 --- a/components/expandables.mdx +++ b/components/expandables.mdx @@ -1,9 +1,11 @@ --- title: "Expandables" -description: "Toggle to display nested properties." +description: "Toggle to display nested properties" icon: 'list-tree' --- +The `` component allows users to toggle the visibility of nested content, particularly useful for displaying complex object properties in API documentation. + @@ -39,10 +41,9 @@ icon: 'list-tree' ## Props - The name of the object you are showing. Used to generate the "Show NAME" and - "Hide NAME" text. + The name of the object you are showing. Used to generate the "Show NAME" and "Hide NAME" text. - Set to true to show the component as open when the page loads. + Set to `true` to show the component as open when the page loads. From ffc414fe8f75c616095a566e785ab37c7aa9bd6d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:41:09 -0700 Subject: [PATCH 03/29] Update Fields component page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add clear introduction explaining field components - Improve consistency in component naming conventions - Remove unnecessary periods from descriptions - Improve punctuation and clarity - Add comma for better readability in example 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- components/fields.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/components/fields.mdx b/components/fields.mdx index 99d0a2c14..0a239587d 100644 --- a/components/fields.mdx +++ b/components/fields.mdx @@ -4,11 +4,11 @@ description: "Set parameters for your API or SDK references" icon: 'letter-text' --- -There are two types of fields: Parameter Fields and Response Fields. +Fields are used to document API parameters and responses. There are two types of fields: Parameter Fields and Response Fields. ## Parameter Field -A `ParamField` component is used to define the parameters for your APIs or SDKs. Adding a `ParamField` will automatically add an [API Playground](/api-playground/overview). +The `` component is used to define parameters for your APIs or SDKs. Adding a `ParamField` automatically adds an [API Playground](/api-playground/overview). An example of a parameter field @@ -47,7 +47,7 @@ A `ParamField` component is used to define the parameters for your APIs or SDKs. Supports `number`, `string`, `bool`, `object`. - Arrays can be defined using the `[]` suffix. For example `string[]`. + Arrays can be defined using the `[]` suffix. For example, `string[]`. @@ -76,7 +76,7 @@ A `ParamField` component is used to define the parameters for your APIs or SDKs. ## Response Field -The `` component is designed to define the return values of an API. Many docs also use `` on pages when you need to list the types of something. +The `` component defines the return values of an API. Many docs also use `` on pages when you need to list the types of something. A response field example @@ -91,23 +91,23 @@ The `` component is designed to define the return values of an AP ### Props - The name of the response value. + The name of the response value - Expected type of the response value - this can be any arbitrary string. + Expected type of the response value. This can be any arbitrary string. - The default value. + The default value - Show "required" beside the field name. + Show "required" beside the field name - Whether a field is deprecated or not. + Whether a field is deprecated From a808b6d60ea5f852c607209f08a62376077cebb8 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:42:28 -0700 Subject: [PATCH 04/29] Update Icons component page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add clear introduction explaining the Icon component - Improve language clarity and flow - Remove unnecessary periods from prop descriptions - Replace 'e.g.' with 'for example' for consistency - Remove trailing space from inline example 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- components/icons.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/components/icons.mdx b/components/icons.mdx index 22d041db0..a6961e616 100644 --- a/components/icons.mdx +++ b/components/icons.mdx @@ -4,6 +4,8 @@ description: "Use icons from popular icon libraries" icon: "flag" --- +The `` component displays icons from Font Awesome, Lucide, or custom icon URLs. + @@ -16,10 +18,10 @@ icon: "flag" ## Inline Icons -The icon will be placed inline when used in a paragraph. +Icons are placed inline when used within a paragraph. ```markdown Inline Icon Example - The documentation you want, effortlessly. + The documentation you want, effortlessly. ``` The documentation you want, effortlessly. @@ -27,15 +29,15 @@ The icon will be placed inline when used in a paragraph. ### Props - A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon. + A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` (only for [Font Awesome](https://fontawesome.com/icons) icons). + One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` (only for [Font Awesome](https://fontawesome.com/icons) icons) - The color of the icon as a hex code (e.g., `#FF5733`) + The color of the icon as a hex code (for example, `#FF5733`) From 988ea188807469a16206cb8c5476c11e04d89f61 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:42:58 -0700 Subject: [PATCH 05/29] Update Mermaid diagrams page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add clear introduction explaining Mermaid's purpose and capabilities - Improve clarity and conciseness of descriptions - Simplify section heading from 'Syntax for Mermaid diagrams' to 'Syntax' - Make language more precise and user-focused - Update code comment to be more generic 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- components/mermaid-diagrams.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/components/mermaid-diagrams.mdx b/components/mermaid-diagrams.mdx index 100fec13d..05f227c09 100644 --- a/components/mermaid-diagrams.mdx +++ b/components/mermaid-diagrams.mdx @@ -4,6 +4,8 @@ description: 'Display diagrams using Mermaid' icon: 'waypoints' --- +Create visual diagrams using Mermaid's text-based syntax. Mermaid lets you build flowcharts, sequence diagrams, Gantt charts, and other diagram types using simple text commands. + ````mdx Mermaid Flowchart Example @@ -29,7 +31,7 @@ icon: 'waypoints' -[Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code. +[Mermaid](https://mermaid.js.org/) is a JavaScript-based diagramming tool that renders markdown-inspired text definitions. ```mermaid flowchart LR @@ -50,14 +52,14 @@ icon: 'waypoints' outside ---> top2 ``` -For a complete list of diagrams supported by Mermaid, check out their [website](https://mermaid.js.org/). +For a complete list of supported diagram types, check out the [Mermaid website](https://mermaid.js.org/). -## Syntax for Mermaid diagrams +## Syntax -To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block. +To create a Mermaid diagram, write your diagram definition inside a Mermaid code block. ````mdx ```mermaid -// Your mermaid code block here +// Your mermaid diagram code here ``` ```` From 1c02f35cf88e19514f92f39f5b8920bd623461f4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:44:04 -0700 Subject: [PATCH 06/29] Update Steps component page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add clear introduction explaining the Steps component - Improve language clarity and consistency - Remove unnecessary periods from prop descriptions - Add Oxford comma for better readability - Make description more action-oriented 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- components/steps.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/components/steps.mdx b/components/steps.mdx index fa0087db2..39e6b20ef 100644 --- a/components/steps.mdx +++ b/components/steps.mdx @@ -4,7 +4,7 @@ description: 'Sequence content using the Steps component' icon: 'list-todo' --- -Steps are the best way to display a series of actions of events to your users. You can add as many steps as desired. +The `` component displays a series of sequential actions or events. You can add as many steps as needed for your workflow. @@ -39,17 +39,17 @@ Steps are the best way to display a series of actions of events to your users. Y ## Steps Props - A list of `Step` components. + A list of `Step` components - The size of the step titles. One of `p`, `h2` and `h3`. + The size of the step titles. One of `p`, `h2`, and `h3` ## Individual Step Props - The content of a step either as plain text, or components. + The content of a step either as plain text or components @@ -61,13 +61,13 @@ Steps are the best way to display a series of actions of events to your users. Y - The title is the primary text for the step and shows up next to the indicator. + The title is the primary text for the step and shows up next to the indicator - The number of the step. + The number of the step - The size of the step titles. One of `p`, `h2` and `h3`. + The size of the step titles. One of `p`, `h2`, and `h3` From 6a70f3842bccc48d40366f79adc80a2f982d2df5 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:44:29 -0700 Subject: [PATCH 07/29] Update Tabs component page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add clear introduction explaining the Tabs component purpose - Improve clarity and user understanding - Remove unnecessary period from prop description - Make description more informative about component functionality 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- components/tabs.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/tabs.mdx b/components/tabs.mdx index 42988439c..49ee89ec9 100644 --- a/components/tabs.mdx +++ b/components/tabs.mdx @@ -4,7 +4,7 @@ description: "Toggle content using the Tabs component" icon: 'panel-top' --- -You can add any number of tabs, and other components inside of tabs. +The `` component organizes content into multiple panels that users can switch between. You can add any number of tabs and include other components inside each tab. @@ -54,5 +54,5 @@ You can add any number of tabs, and other components inside of tabs. ## Tab Props - The title of the tab. Short titles are easier to navigate. + The title of the tab. Short titles are easier to navigate From bc10e94d82ced6e5d12cdcd67c0e6af530453518 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:44:56 -0700 Subject: [PATCH 08/29] Update Migrations guide page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Improve language clarity and conciseness - Remove unnecessary periods from command descriptions - Enhance section structure with proper headings - Update terminology for consistency - Add OpenAPI migration section header for better organization 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- guides/migration.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/guides/migration.mdx b/guides/migration.mdx index c72fa6542..f568d5d9f 100644 --- a/guides/migration.mdx +++ b/guides/migration.mdx @@ -4,7 +4,7 @@ description: "How to migrate documentation from your existing provider" icon: "import" --- -You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to convert your existing documentation to Mintlify. +Use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to convert your existing documentation to Mintlify. We currently support automated migration for: @@ -88,14 +88,14 @@ We currently support automated migration for: -Don't see your docs provider or have a home grown system? We can still help! Please [contact support](/contact-support). +Don't see your documentation provider or have a custom system? We can still help! Please [contact support](/contact-support). ## Commands -- `mintlify-scrape section [url]` - Scrapes multiple pages in a site. -- `mintlify-scrape page [url]` - Scrapes a single page in a site. +- `mintlify-scrape section [url]` - Scrapes multiple pages in a site +- `mintlify-scrape page [url]` - Scrapes a single page in a site -The commands will automatically detect the framework. +The commands automatically detect the framework. ## Installation @@ -105,7 +105,7 @@ First, install the package: npm i @mintlify/scraping ``` -One-time use: +### One-time use @@ -120,13 +120,13 @@ npx @mintlify/scraping@latest page [url] -Global installation: +### Global installation ```bash npm install @mintlify/scraping@latest -g ``` -Global usage: +### Global usage @@ -141,6 +141,8 @@ mintlify-scrape page [url] +### OpenAPI migration + Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint. ```bash From c3585bf62579090ebb9a18bb2216b19c6ab15b62 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:45:37 -0700 Subject: [PATCH 09/29] Update React components page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Improve language clarity and conciseness throughout - Simplify and tighten explanatory text - Fix capitalization in performance best practices - Remove redundant phrases for better flow - Enhance readability and user experience 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- react-components.mdx | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/react-components.mdx b/react-components.mdx index 537ef8eac..7017f1a25 100644 --- a/react-components.mdx +++ b/react-components.mdx @@ -7,9 +7,7 @@ icon: "react" import { Counter } from "/snippets/counter.mdx"; import { ColorGenerator } from "/snippets/color-generator.jsx"; -[React components](https://react.dev) are a powerful way to create interactive and reusable elements in your documentation. - -You can use React directly in your MDX files without any additional setup. +[React components](https://react.dev) are a powerful way to create interactive and reusable elements in your documentation. Use React directly in your MDX files without any additional setup. ## Using React Components @@ -34,13 +32,13 @@ export const Counter = () => { } ``` -The `Counter` component can then be used in your MDX files like this: +Use the `Counter` component in your MDX files like this: ```mdx ``` -And the component will be rendered as a React component in the MDX file. +The component renders as an interactive React component in the MDX file. @@ -53,10 +51,10 @@ import { ColorGenerator } from "/snippets/color-generator.jsx" ``` - But unlike regular React, you can't import components from every MDX file. Re-usable components can only be referenced from MDX files within the `snippets` folder. + Unlike regular React, you can't import components from every MDX file. Reusable components can only be referenced from MDX files within the `snippets` folder. -After importing the component, you can use it in your MDX files like this: +After importing the component, use it in your MDX files like this: ```mdx @@ -66,7 +64,7 @@ Learn more about [reusable snippets](/reusable-snippets). ### Complex Example -You can also build much more complex components. Here's an example of a color generator component that uses multiple React hooks: +You can build much more complex components. Here's an example of a color generator component that uses multiple React hooks: ```mdx /snippets/color-generator.jsx [expandable] export const ColorGenerator = () => { @@ -181,13 +179,13 @@ export const ColorGenerator = () => { } ``` -The above component can then be used in your MDX files like this: +Use the above component in your MDX files like this: ```mdx ``` -And the component will be rendered as a React component in the MDX file. +The component renders as an interactive React component in the MDX file. @@ -202,9 +200,9 @@ And the component will be rendered as a React component in the MDX file. - **Accessibility**: Ensure dynamic content changes are announced to screen readers - - **Optimize Dependency Arrays**: Include only necessary dependencies in your `useEffect` dependency arrays - - **Memoize Complex Calculations**: Use `useMemo` or `useCallback` for expensive operations - - **Reduce Re-renders**: Break large components into smaller ones to prevent cascading re-renders - - **Lazy Loading**: Consider lazy loading complex components to improve initial page load time + - **Optimize dependency arrays**: Include only necessary dependencies in your `useEffect` dependency arrays + - **Memoize complex calculations**: Use `useMemo` or `useCallback` for expensive operations + - **Reduce re-renders**: Break large components into smaller ones to prevent cascading re-renders + - **Lazy loading**: Consider lazy loading complex components to improve initial page load time From 8cc567311697cef2c516f74f9e87253007c709f2 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:46:06 -0700 Subject: [PATCH 10/29] Update Redirects and broken links page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Improve language clarity and conciseness - Remove unnecessary words like 'Simply' and 'will' - Use present tense for more direct communication - Fix preposition usage for better grammar - Streamline explanations for better readability 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- settings/broken-links.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/settings/broken-links.mdx b/settings/broken-links.mdx index 759e040d8..22b52f849 100644 --- a/settings/broken-links.mdx +++ b/settings/broken-links.mdx @@ -4,21 +4,21 @@ description: "Tools to help prevent invalid links" icon: 'link-2' --- -When you change the path of a file in your docs folder, it will also change the path of the URL to that page. This may happen when restructuring your docs or changing the sidebar title. +When you change the path of a file in your docs folder, it also changes the URL path to that page. This may happen when restructuring your docs or changing the sidebar title. ## Broken Links -Catch broken links with our CLI. Simply [install the CLI](/installation) and run the command: +Catch broken links with our CLI. [Install the CLI](/installation) and run the command: ```bash mint broken-links ``` -The CLI will identify any relative links in your docs that don't exist. +The CLI identifies any relative links in your docs that don't exist. ## Redirects -Set up 301 redirects by adding the `redirects` field into your `docs.json` file. +Set up 301 redirects by adding the `redirects` field to your `docs.json` file. ```json "redirects": [ @@ -29,9 +29,9 @@ Set up 301 redirects by adding the `redirects` field into your `docs.json` file. ] ``` -This will permanently redirect `/source/path` to `/destination/path` so that you don't lose any previous SEO for the original page. +This permanently redirects `/source/path` to `/destination/path` so that you don't lose any previous SEO for the original page. -To match a wildcard path, use `*` after a parameter. In this example, `/beta/:slug*` will match `/beta/introduction` and redirects it to `/v2/introduction`. +To match a wildcard path, use `*` after a parameter. In this example, `/beta/:slug*` matches `/beta/introduction` and redirects it to `/v2/introduction`. ```json "redirects": [ From 42682671055639cc3f8648a5df1d3ad169c4fb8c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:46:31 -0700 Subject: [PATCH 11/29] Update Support integrations page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Improve language clarity and directness - Remove unnecessary words for better flow - Use more direct phrasing for instructions - Simplify conditional language for better readability 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- integrations/support/overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/integrations/support/overview.mdx b/integrations/support/overview.mdx index 6a98f8a78..442447e14 100644 --- a/integrations/support/overview.mdx +++ b/integrations/support/overview.mdx @@ -37,7 +37,7 @@ horizontal ## Enabling Support Integrations -You can integrate widgets onto your docs for customer support. Add the `integrations` field into your `docs.json` file with your respective app ID. +Integrate customer support widgets into your documentation. Add the `integrations` field to your `docs.json` file with your respective app ID. ```json "integrations": { @@ -46,4 +46,4 @@ You can integrate widgets onto your docs for customer support. Add the `integrat } ``` -If you'd like to request a customer support integration, please let us know in [our community](https://join.slack.com/t/mintlify-users/shared_invite/zt-1xfzz6x35-f4o4WCYfpvLhSj3O7WAOMA). +To request a customer support integration, let us know in [our community](https://join.slack.com/t/mintlify-users/shared_invite/zt-1xfzz6x35-f4o4WCYfpvLhSj3O7WAOMA). From e5a0e6f5b968de6ca533e5f515bf4f9392d32a1a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 13:47:18 -0700 Subject: [PATCH 12/29] Update CI checks page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Improve language clarity and conciseness throughout - Remove unnecessary words and phrases - Use present tense for more direct communication - Fix grammar issues and improve flow - Replace 'in-built' with 'built-in' for standard terminology - Streamline explanations for better readability 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- settings/ci.mdx | 34 ++++++++++++++-------------------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index 3d8ced709..3e0a59ebd 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -8,19 +8,17 @@ icon: "circle-check" CI checks are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=docs-ci), an add-on for other plans, and for GitHub. -Use CI checks to lint your docs for errors, and give you warnings before you deploy. +Use CI checks to lint your docs for errors and provide warnings before you deploy. ## Installation -To begin, you will need to have followed the steps on the [GitHub](/settings/github) page. +To begin, follow the steps on the [GitHub](/settings/github) page. -For GitHub Apps, you can choose to only give permissions to a single repository. -We highly recommend you do so as we only need access to the repository where -your docs are hosted. +For GitHub Apps, you can choose to give permissions to only a single repository. We highly recommend you do so as we only need access to the repository where your docs are hosted. ## Configuration -You can configure the CI checks enabled for a deployment on the Mintlify dashboard by navigating to the 'Add-Ons' tab. There you can enable or disable the checks you'd like to run. +Configure the CI checks enabled for a deployment on the Mintlify dashboard by navigating to the 'Add-Ons' tab. There you can enable or disable the checks you'd like to run. When enabling checks, you can choose to run them at a `Warning` or `Blocking` level. @@ -41,20 +39,18 @@ CI checks are configured to run on commits to your configured deployment branch, ### Broken Links -Similarly to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, we will automatically check your docs for broken links. -To see the results of this check, you can visit GitHub's check results page for a specific commit. +Similar to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, we automatically check your docs for broken links. To see the results of this check, visit GitHub's check results page for a specific commit. ### Vale [Vale](https://vale.sh/) is an open-source rule-based prose linter which supports a range of document types, including Markdown and MDX. -Mintlify supports automatically running Vale in a CI check, and displaying the results as a check status. +Mintlify supports automatically running Vale in a CI check and displaying the results as a check status. #### Configuration -If you have a `.vale.ini` file in the root the content directory for your deployment, we will automatically use that configuration file. -We will also automatically use any configuration files in your specified `stylesPath`. +If you have a `.vale.ini` file in the root content directory for your deployment, we automatically use that configuration file. We also automatically use any configuration files in your specified `stylesPath`. -Don't have a Vale config or not sure where to get started? Don't worry, Mintlify has a default configuration that will automatically be used if one is not provided. +Don't have a Vale config or not sure where to get started? Don't worry, Mintlify has a default configuration that automatically loads if one is not provided. Please note that for security reasons, we are unable to support any absolute `stylesPath`, or `stylesPath` which include `..` values. Please use relative paths and include the `stylesPath` in your repository. @@ -62,9 +58,9 @@ Please note that for security reasons, we are unable to support any absolute `st #### Packages Vale supports a range of [packages](https://vale.sh/docs/keys/packages), which can be used to check for spelling and style errors. -Any packages you include in your repository under the correct `stylesPath` will be automatically installed and used in your Vale configuration. +Any packages you include in your repository under the correct `stylesPath` are automatically installed and used in your Vale configuration. -For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they will automatically be downloaded and used in your Vale configuration. +For packages not included in your repository, you may specify any packages from the [Vale package registry](https://vale.sh/explorer), and they are automatically downloaded and used in your Vale configuration. Please note that for security reasons, we are unable to support automatically downloading packages that are not from the [Vale package registry](https://vale.sh/explorer). @@ -73,7 +69,7 @@ Please note that for security reasons, we are unable to support automatically do #### Vale with MDX Vale does not natively support MDX, but Vale's author has provided a [custom extension](https://github.com/errata-ai/MDX) to support it. -If you'd prefer not to use this extension, we recommend the following lines in your `.vale.ini` file: +If you prefer not to use this extension, we recommend the following lines in your `.vale.ini` file: ```ini [formats] mdx = md @@ -89,9 +85,7 @@ BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ (?sm)^({.+.*}) ``` -To use Vale's in-document comments, use MDX-style comments `{/* ... */}`. -If you use the `CommentDelimiters = {/*, */}` [setting](https://vale.sh/docs/keys/commentdelimiters) in your configuration, Vale will automatically interpret these comments while linting. -This means you can easily use Vale's in-built features, like skipping lines or sections. +To use Vale's in-document comments, use MDX-style comments `{/* ... */}`. If you use the `CommentDelimiters = {/*, */}` [setting](https://vale.sh/docs/keys/commentdelimiters) in your configuration, Vale automatically interprets these comments while linting. This means you can easily use Vale's built-in features, like skipping lines or sections. ```mdx {/* vale off */} @@ -102,7 +96,7 @@ This text will be ignored by Vale ``` -If you choose not to use `CommentDelimiters`, but still choose to use Vale's comments, you must wrap any Vale comments in MDX comments `{/* ... */}`. For example: +If you choose not to use `CommentDelimiters` but still choose to use Vale's comments, you must wrap any Vale comments in MDX comments `{/* ... */}`. For example: ```mdx {/* */} @@ -111,4 +105,4 @@ This text will be ignored by Vale {/* */} ``` -Please note that these comment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document. +These comment tags are not supported within Mintlify components but can be used anywhere at the base level of a document. From 35916583eb483bb8a62411c7caf1018a253d7464 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 14:34:39 -0700 Subject: [PATCH 13/29] quickstart edits --- quickstart.mdx | 82 +++++++++++++++++++++----------------------------- 1 file changed, 35 insertions(+), 47 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index 84d3b3036..d6e0b3978 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -4,9 +4,9 @@ description: "Deploy your documentation in minutes" icon: "rocket" --- -This quickstart guide shows you how to set up and deploy your documentation site in minutes using Mintlify. +This quickstart guide shows you how to set up and deploy your documentation site in minutes. -After completing this guide, you'll have a live documentation site ready to customize and expand. +After completing this guide, you will have a live documentation site ready to customize and expand. @@ -14,9 +14,9 @@ After completing this guide, you'll have a live documentation site ready to cust -## Getting Started +## Getting started -After completing the onboarding process, your documentation site automatically deploys to a unique URL with this format: +After you complete the onboarding process, your documentation site automatically deploys to a unique URL with this format: ``` https://.mintlify.app @@ -29,7 +29,7 @@ Find your URL on the Overview page of your [dashboard](https://dashboard.mintlif Mintlify Domain -This URL is available immediately and updates automatically when you make changes to your documentation. Use this URL for testing and sharing with your team during development. +Your site's URL is available immediately. Use this URL for testing and sharing with your team while you are setting up your docs site. ### Install the GitHub App @@ -37,10 +37,11 @@ Mintlify provides a GitHub App that automates deployment when you push changes t Install the GitHub App by following the instructions from the onboarding checklist or your dashboard. -1. Navigate to **Settings** in your Mintlify dashboard -2. Select **GitHub App** from the sidebar -3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page -4. Select the organization or user account where you want to install the app, then select the repositories you want to connect +1. Navigate to **Settings** in your Mintlify dashboard. +2. Select **GitHub App** from the sidebar. +3. Select **Install GitHub App**. This opens a new tab to the GitHub App installation page. +4. Select the organization or user account where you want to install the app. +5. Select the repositories that you want to connect. GitHub App Installation @@ -51,19 +52,19 @@ Install the GitHub App by following the instructions from the onboarding checkli Update the GitHub App permissions if you move your documentation to a different repository. -### Authorize your GitHub Account +### Authorize your GitHub account -1. Navigate to **Settings** in your Mintlify dashboard -2. Select **My Profile** from the sidebar -3. Select **Authorize GitHub account**. This opens a new tab to the GitHub authorization page +1. Navigate to **Settings** in your Mintlify dashboard. +2. Select **My Profile** from the sidebar. +3. Select **Authorize GitHub account**. This opens a new tab to the GitHub authorization page. An admin for your GitHub organization may need to authorize your account depending on your organization settings. -## Editing Workflows +## Editing workflows -Mintlify offers two workflows for creating and maintaining your documentation. +Mintlify offers two workflows for creating and maintaining your documentation: For users who prefer working with existing tools in their local environment. Click to jump to this section. @@ -73,7 +74,7 @@ Mintlify offers two workflows for creating and maintaining your documentation. For users who prefer a visual interface in their web browser. Click to jump to this section. -## Code-Based Workflow +## Code-based workflow The code-based workflow integrates with your existing development environment and Git repositories. This workflow is best for technical teams who want to manage documentation alongside code. @@ -81,33 +82,20 @@ The code-based workflow integrates with your existing development environment an To work locally with your documentation, install the Command Line Interface (CLI), called [mint](https://www.npmjs.com/package/mint), by running this command in your terminal: - - -```bash npm -npm install -g mint -``` - - -```bash yarn -yarn global add mint -``` - - -```bash pnpm -pnpm add -g mint +```bash +npm i -g mint ``` - - You need Node.js installed on your machine. If you encounter installation issues, check the troubleshooting guide. -### Edit the Documentation +### Edit the documentation After setting up your environment, you can start editing your documentation files. For example, update the title of the introduction page: -Open your repository created during onboarding, find the `index.mdx` file, and locate the top of the file: +1. Open your repository created during onboarding. +2. Open `index.mdx` and locate the top of the file: ```mdx index.mdx --- @@ -116,7 +104,7 @@ description: "This is the introduction to the documentation" --- ``` -Update the `title` field to `"Hello World"`. +3. Update the `title` field to `"Hello World"`. ```mdx index.mdx {2} --- @@ -125,9 +113,9 @@ description: "This is the introduction to the documentation" --- ``` -### Preview the Changes +### Preview the changes -To preview the changes locally, run this command: +To preview the changes locally, run the following command: ```bash mint dev @@ -140,23 +128,23 @@ Your preview will be available at `localhost:3000`. Mintlify Dev -### Push the Changes +### Push the changes -When you're ready to publish your changes, push them to your repository. +When you are ready to publish your changes, push them to your repository. Mintlify automatically detects the changes, builds your documentation, and deploys the updates to your site. Monitor the deployment status in your GitHub repository commit history or the [dashboard](https://dashboard.mintlify.com). -After deployment completes, your latest update will be available at `.mintlify.app`. +After the deployment completes, your latest update will be available at `.mintlify.app`. Optionally, skip the web editor workflow and jump to adding a custom domain. -## Web Editor Workflow +## Web editor workflow The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interface for creating and editing documentation. This workflow is best for people who want to work in their web browser without additional local development tools. -### Access the Web Editor +### Access the web editor 1. Log in to your [dashboard](https://dashboard.mintlify.com). 2. Select **Editor** on the left sidebar. @@ -170,7 +158,7 @@ The web editor workflow provides a what-you-see-is-what-you-get (WYSIWYG) interf The Mintlify web editor in the visual editor mode -### Edit the Documentation +### Edit the documentation In the web editor, you can navigate through your documentation files in the sidebar. Let's update the introduction page: @@ -187,7 +175,7 @@ Then, in the editor, update the title field to "Hello World". The editor provides a rich set of formatting tools and components. Type / in the editor to open the command menu and access these tools. -### Publish Your Changes +### Publish your changes When you're satisfied with your edits, select the **Publish** button in the top-right corner. Your changes are immediately deployed to your documentation site. @@ -197,11 +185,11 @@ When you're satisfied with your edits, select the **Publish** button in the top- For more details about using the web editor, including using branches and pull requests to collaborate and preview changes, see our [web editor documentation](/editor). -## Adding a Custom Domain +## Adding a custom domain While your `.mintlify.app` subdomain works well for testing and development, most teams prefer using a custom domain for production documentation. -To add a custom domain, navigate to `Settings` > `Custom Domain` from the dashboard. +To add a custom domain, navigate to the [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) page in your dashboard. Custom Domain @@ -220,7 +208,7 @@ Enter your domain (for example, `docs.yourcompany.com`) and follow the provided DNS changes can take up to 48 hours to propagate, though changes often complete much sooner. -## Next Steps +## Next steps Congratulations! You have successfully deployed your documentation site with Mintlify. Here are suggested next steps to enhance your documentation: From 9951c26e9bbd740f3d19713c015eff955a9bd6df Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 15:16:18 -0700 Subject: [PATCH 14/29] Update cards --- components/cards.mdx | 132 +++++++++++++++++++++++-------------------- 1 file changed, 71 insertions(+), 61 deletions(-) diff --git a/components/cards.mdx b/components/cards.mdx index 7ee626e7f..06cdef615 100644 --- a/components/cards.mdx +++ b/components/cards.mdx @@ -1,50 +1,66 @@ --- title: "Cards" -description: "Highlight main points or links with customizable icons" -icon: 'square-mouse-pointer' +description: "Highlight main points or links with customizable layouts andicons" +icon: "square-mouse-pointer" --- - +Use cards to create visual containers for content. Cards are flexible containers that can include text, icons, images, and links. + +## Basic card + + This is how you use a card with an icon and a link. Clicking on this card brings you to the Columns page. - - ```mdx Card Example - - This is how you use a card with an icon and a link. Clicking on this card - brings you to the Columns page. - - ``` - -```mdx Image Card Example - - Here is an example of a card with an image +```mdx Card example + + This is how you use a card with an icon and a link. Clicking on this card + brings you to the Columns page. ``` - +## Card variations -## Horizontal card +Cards support several layout and styling options to fit different content needs. -Add a `horizontal` property to display cards horizontally. +### Horizontal layout - - Here is an example of a horizontal card +Add the `horizontal` property to display cards in a more compact, horizontal layout. + + + This is an example of a horizontal card. -## Image card +```mdx Horizontal card example + + This is an example of a horizontal card. + +``` + +### Image cards -Add an `img` property to display an image on the top of the card. +Add an `img` property to display an image at the top of the card. - - Here is an example of a card with an image + + This is an example of a card with an image. -## Link card +```mdx Image card example + + This is an example of a card with an image. + +``` -You can customize the CTA and whether or not to display the arrow on the card. By default, the arrow will only show for external links. +### Link cards with custom CTAs + +You can customize the call-to-action text and control whether an arrow appears. By default, arrows only show for external links. + + + This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page. + +```mdx Link card example - This is how you use a card with an icon and a link. Clicking on this card - brings you to the Columns page. + This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page. - - - ```mdx Card Example - - This is how you use a card with an icon and a link. Clicking on this card - brings you to the Columns page. - - ``` - +``` ## Grouping cards -You can group cards in [columns](/components/columns). +Use the [Columns component](/components/columns) to organize multiple cards side by side. - + This is the first card. - + This is the second card. -## Props +```mdx Columns example + + + This is the first card. + + + This is the second card. + + +``` + +## Properties - The title of the card + The title displayed on the card - A [Font Awesome icon](https://fontawesome.com/icons), [Lucide - icon](https://lucide.dev/icons), or JSX compatible SVG code in `icon={}`. - - To generate JSX compatible SVG code: - + Icon to display on the card. Use a [Font Awesome icon](https://fontawesome.com/icons) name, [Lucide icon](https://lucide.dev/icons) name, or JSX-compatible SVG code wrapped in `icon={}`. + + For custom SVG icons: 1. Use the [SVGR converter](https://react-svgr.com/playground/). 2. Copy the code inside the `` tag. - 3. Paste the code into your card. Make sure to only copy and paste the code inside the `` tag. - 4. You may need to decrease the height and width to make the image fit. + 3. Paste the code into your card. + 4. Adjust height and width as needed. - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` + Font Awesome icon style: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, or `brands`. - The color of the icon as a hex code + Icon color as a hex code (e.g., `#FF6B6B`). - The url that clicking on the card would navigate the user to + URL to navigate to when the card is clicked. - Makes the card more compact and horizontal + Display the card in a compact horizontal layout. - The url or local path to an image to display on the top of the card + URL or local path to an image displayed at the top of the card. - Label for the action button + Custom text for the action button. - Enable or disable the link arrow icon + Show or hide the link arrow icon. From 8b863b20cca46d81589340e272dc8b34cfa487db Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 15:18:54 -0700 Subject: [PATCH 15/29] Apply style lessons learned from quickstart and cards feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Use action-oriented introductions ("Use X to..." instead of "The X component...") - Apply sentence case to all section headings ("Properties" not "Props") - Use "Properties" consistently instead of "Props" - Remove unnecessary periods from property descriptions - Update component headings to sentence case - Make language more direct and user-focused 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- components/expandables.mdx | 10 +++++----- components/fields.mdx | 10 +++++----- components/icons.mdx | 6 +++--- components/steps.mdx | 6 +++--- components/tabs.mdx | 4 ++-- 5 files changed, 18 insertions(+), 18 deletions(-) diff --git a/components/expandables.mdx b/components/expandables.mdx index f5fe1e5e0..7c536edda 100644 --- a/components/expandables.mdx +++ b/components/expandables.mdx @@ -1,10 +1,10 @@ --- title: "Expandables" description: "Toggle to display nested properties" -icon: 'list-tree' +icon: "list-tree" --- -The `` component allows users to toggle the visibility of nested content, particularly useful for displaying complex object properties in API documentation. +Use expandables to show and hide nested content within response fields. Expandables are particularly useful for displaying complex object properties in API documentation. @@ -38,12 +38,12 @@ The `` component allows users to toggle the visibility of nested con -## Props +## Properties - The name of the object you are showing. Used to generate the "Show NAME" and "Hide NAME" text. + The name of the object you are showing. Used to generate the "Show NAME" and "Hide NAME" text - Set to `true` to show the component as open when the page loads. + Set to `true` to show the component as open when the page loads diff --git a/components/fields.mdx b/components/fields.mdx index 0a239587d..65c0699a9 100644 --- a/components/fields.mdx +++ b/components/fields.mdx @@ -4,9 +4,9 @@ description: "Set parameters for your API or SDK references" icon: 'letter-text' --- -Fields are used to document API parameters and responses. There are two types of fields: Parameter Fields and Response Fields. +Use fields to document API parameters and responses. There are two types of fields: parameter fields and response fields. -## Parameter Field +## Parameter field The `` component is used to define parameters for your APIs or SDKs. Adding a `ParamField` automatically adds an [API Playground](/api-playground/overview). @@ -36,7 +36,7 @@ The `` component is used to define parameters for your APIs or SDKs. -### Props +### Properties Whether it is a query, path, body, or header parameter followed by the name @@ -74,7 +74,7 @@ The `` component is used to define parameters for your APIs or SDKs. Description of the parameter (markdown enabled) -## Response Field +## Response field The `` component defines the return values of an API. Many docs also use `` on pages when you need to list the types of something. @@ -88,7 +88,7 @@ The `` component defines the return values of an API. Many docs a ``` -### Props +### Properties The name of the response value diff --git a/components/icons.mdx b/components/icons.mdx index a6961e616..c0a6cbd6a 100644 --- a/components/icons.mdx +++ b/components/icons.mdx @@ -4,7 +4,7 @@ description: "Use icons from popular icon libraries" icon: "flag" --- -The `` component displays icons from Font Awesome, Lucide, or custom icon URLs. +Use icons from Font Awesome, Lucide, or custom icon URLs to enhance your documentation. @@ -16,7 +16,7 @@ The `` component displays icons from Font Awesome, Lucide, or custom icon -## Inline Icons +## Inline icons Icons are placed inline when used within a paragraph. @@ -26,7 +26,7 @@ Icons are placed inline when used within a paragraph. The documentation you want, effortlessly. -### Props +### Properties A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon diff --git a/components/steps.mdx b/components/steps.mdx index 39e6b20ef..e25d3ad85 100644 --- a/components/steps.mdx +++ b/components/steps.mdx @@ -4,7 +4,7 @@ description: 'Sequence content using the Steps component' icon: 'list-todo' --- -The `` component displays a series of sequential actions or events. You can add as many steps as needed for your workflow. +Use steps to display a series of sequential actions or events. You can add as many steps as needed for your workflow. @@ -36,7 +36,7 @@ The `` component displays a series of sequential actions or events. You c -## Steps Props +## Steps properties A list of `Step` components @@ -46,7 +46,7 @@ The `` component displays a series of sequential actions or events. You c The size of the step titles. One of `p`, `h2`, and `h3` -## Individual Step Props +## Individual step properties The content of a step either as plain text or components diff --git a/components/tabs.mdx b/components/tabs.mdx index 49ee89ec9..75d639c28 100644 --- a/components/tabs.mdx +++ b/components/tabs.mdx @@ -4,7 +4,7 @@ description: "Toggle content using the Tabs component" icon: 'panel-top' --- -The `` component organizes content into multiple panels that users can switch between. You can add any number of tabs and include other components inside each tab. +Use tabs to organize content into multiple panels that users can switch between. You can add any number of tabs and include other components inside each tab. @@ -51,7 +51,7 @@ The `` component organizes content into multiple panels that users can swi -## Tab Props +## Properties The title of the tab. Short titles are easier to navigate From fb604507ae40320eb1f570fab3f66b1147a2a6b9 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:07:42 -0700 Subject: [PATCH 16/29] fix typo --- components/cards.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/cards.mdx b/components/cards.mdx index 06cdef615..f724c5452 100644 --- a/components/cards.mdx +++ b/components/cards.mdx @@ -1,6 +1,6 @@ --- title: "Cards" -description: "Highlight main points or links with customizable layouts andicons" +description: "Highlight main points or links with customizable layouts and icons" icon: "square-mouse-pointer" --- From 4b25c8d19e12b79e880907796d57508839a6dd28 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:07:52 -0700 Subject: [PATCH 17/29] review exapandables --- components/expandables.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/components/expandables.mdx b/components/expandables.mdx index 7c536edda..45f8a91e6 100644 --- a/components/expandables.mdx +++ b/components/expandables.mdx @@ -20,9 +20,7 @@ Use expandables to show and hide nested content within response fields. Expandab - - -```mdx Expandable Example +```mdx Expandable example @@ -36,14 +34,12 @@ Use expandables to show and hide nested content within response fields. Expandab ``` - - ## Properties - The name of the object you are showing. Used to generate the "Show NAME" and "Hide NAME" text + The name of the object you are showing. - Set to `true` to show the component as open when the page loads + Set to `true` for the expandable to open when the page loads From cd5a6b377544a1fa7805ca10be66e05264d52156 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:18:09 -0700 Subject: [PATCH 18/29] update fields --- components/fields.mdx | 56 ++++++++++++++++--------------------------- 1 file changed, 20 insertions(+), 36 deletions(-) diff --git a/components/fields.mdx b/components/fields.mdx index 65c0699a9..7a06d6d1d 100644 --- a/components/fields.mdx +++ b/components/fields.mdx @@ -1,7 +1,7 @@ --- title: "Fields" description: "Set parameters for your API or SDK references" -icon: 'letter-text' +icon: "letter-text" --- Use fields to document API parameters and responses. There are two types of fields: parameter fields and response fields. @@ -14,72 +14,56 @@ The `` component is used to define parameters for your APIs or SDKs. An example of a parameter field - - -```mdx Path Example - +```mdx + An example of a parameter field ``` -```mdx Body Example - - The age of the user. Cannot be less than 0 - -``` - -```mdx Response Example - - A response field example - -``` - - - ### Properties - Whether it is a query, path, body, or header parameter followed by the name + Whether the parameter is a query, path, body, or header. Followed by the parameter name. - Expected type of the parameter's value + Expected type of the parameter's value. - Supports `number`, `string`, `bool`, `object`. + Supports `number`, `string`, `boolean`, `object`. Arrays can be defined using the `[]` suffix. For example, `string[]`. - Indicate whether the parameter is required + Indicate whether the parameter is required. - Indicate whether the parameter is deprecated + Indicate whether the parameter is deprecated. - Default value used by the server if the request does not provide a value + Default value used by the server if the request does not provide a value. - Value that will be used to initialize the playground + Value that will be used to initialize the playground. - Placeholder text for the input in the playground + Placeholder text for the input in the playground. - Description of the parameter (markdown enabled) + Description of the parameter (Markdown-enabled). ## Response field -The `` component defines the return values of an API. Many docs also use `` on pages when you need to list the types of something. +The `` component defines the return values of an API. - A response field example + An example of a response field ```mdx @@ -91,7 +75,7 @@ The `` component defines the return values of an API. Many docs a ### Properties - The name of the response value + The name of the response value. @@ -99,21 +83,21 @@ The `` component defines the return values of an API. Many docs a - The default value + The default value. - Show "required" beside the field name + Indicate whether the response is required. - Whether a field is deprecated + Whether a field is deprecated. - Labels that are shown before the name of the field + Labels that are shown before the name of the field. - Labels that are shown after the name of the field + Labels that are shown after the name of the field. From 6b73c6b156bbf7e839fb3880a4bfaf0adc51566d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:20:35 -0700 Subject: [PATCH 19/29] update icons --- components/icons.mdx | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/components/icons.mdx b/components/icons.mdx index c0a6cbd6a..4f7475930 100644 --- a/components/icons.mdx +++ b/components/icons.mdx @@ -8,38 +8,34 @@ Use icons from Font Awesome, Lucide, or custom icon URLs to enhance your documen - - -```mdx Icon Example +```mdx Icon example ``` - - ## Inline icons Icons are placed inline when used within a paragraph. -```markdown Inline Icon Example The documentation you want, effortlessly. -``` +```markdown Inline icon example The documentation you want, effortlessly. +``` -### Properties +## Properties - A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon + A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon. - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` (only for [Font Awesome](https://fontawesome.com/icons) icons) + For [Font Awesome](https://fontawesome.com/icons) icons only: One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`. - The color of the icon as a hex code (for example, `#FF5733`) + The color of the icon as a hex code (for example, `#FF5733`). - The size of the icon in pixels - \ No newline at end of file + The size of the icon in pixels. + From cf88666ce092f77a64d57ff045a94411db9fb908 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:27:04 -0700 Subject: [PATCH 20/29] update mermaid --- components/icons.mdx | 2 +- components/mermaid-diagrams.mdx | 16 +++++++--------- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/components/icons.mdx b/components/icons.mdx index 4f7475930..d703d2858 100644 --- a/components/icons.mdx +++ b/components/icons.mdx @@ -4,7 +4,7 @@ description: "Use icons from popular icon libraries" icon: "flag" --- -Use icons from Font Awesome, Lucide, or custom icon URLs to enhance your documentation. +Use icons from Font Awesome, Lucide, URLs, or files in your project to enhance your documentation. diff --git a/components/mermaid-diagrams.mdx b/components/mermaid-diagrams.mdx index 05f227c09..9cd507de0 100644 --- a/components/mermaid-diagrams.mdx +++ b/components/mermaid-diagrams.mdx @@ -1,14 +1,16 @@ --- -title: 'Mermaid' -description: 'Display diagrams using Mermaid' -icon: 'waypoints' +title: "Mermaid" +description: "Display diagrams using Mermaid" +icon: "waypoints" --- -Create visual diagrams using Mermaid's text-based syntax. Mermaid lets you build flowcharts, sequence diagrams, Gantt charts, and other diagram types using simple text commands. +[Mermaid](https://mermaid.js.org/) lets you build flowcharts, sequence diagrams, Gantt charts, and other diagrams using text and code. + +For a complete list of supported diagram types and syntax, see the [Mermaid documentation](https://mermaid.js.org/intro/). -````mdx Mermaid Flowchart Example +````mdx Mermaid flowchart example ```mermaid flowchart LR subgraph subgraph1 @@ -31,8 +33,6 @@ Create visual diagrams using Mermaid's text-based syntax. Mermaid lets you build -[Mermaid](https://mermaid.js.org/) is a JavaScript-based diagramming tool that renders markdown-inspired text definitions. - ```mermaid flowchart LR subgraph subgraph1 @@ -52,8 +52,6 @@ Create visual diagrams using Mermaid's text-based syntax. Mermaid lets you build outside ---> top2 ``` -For a complete list of supported diagram types, check out the [Mermaid website](https://mermaid.js.org/). - ## Syntax To create a Mermaid diagram, write your diagram definition inside a Mermaid code block. From d8719315ce8933ea27b774a75b0e9f83a6b4812a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:30:56 -0700 Subject: [PATCH 21/29] update steps --- components/steps.mdx | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/components/steps.mdx b/components/steps.mdx index e25d3ad85..cd80b3fb8 100644 --- a/components/steps.mdx +++ b/components/steps.mdx @@ -1,10 +1,10 @@ --- -title: 'Steps' -description: 'Sequence content using the Steps component' -icon: 'list-todo' +title: "Steps" +description: "Sequence content using the Steps component" +icon: "list-todo" --- -Use steps to display a series of sequential actions or events. You can add as many steps as needed for your workflow. +Use steps to display a series of sequential actions or events. You can add as many steps as needed. @@ -18,9 +18,7 @@ Use steps to display a series of sequential actions or events. You can add as ma - - -```mdx Steps Example +```mdx Steps example These are instructions or content that only pertain to the first step. @@ -34,40 +32,38 @@ Use steps to display a series of sequential actions or events. You can add as ma ``` - - ## Steps properties - A list of `Step` components + A list of `Step` components. - The size of the step titles. One of `p`, `h2`, and `h3` + The size of the step titles. One of `p`, `h2`, and `h3`. ## Individual step properties - The content of a step either as plain text or components + The content of a step either as plain text or components. - A [Font Awesome icon](https://fontawesome.com/icons), [Lucide icon](https://lucide.dev/icons), or SVG code in `icon={}` + A [Font Awesome icon](https://fontawesome.com/icons), [Lucide icon](https://lucide.dev/icons), or SVG code in `icon={}`. - One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` + For Font Awesome icons only: One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`. - The title is the primary text for the step and shows up next to the indicator + The title is the primary text for the step and shows up next to the indicator. - The number of the step + The number of the step. - The size of the step titles. One of `p`, `h2`, and `h3` + The size of the step titles. One of `p`, `h2`, and `h3`. From c5b2980736ea980007cd1cdde5678910b2a274eb Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:32:47 -0700 Subject: [PATCH 22/29] update tabs --- components/tabs.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/components/tabs.mdx b/components/tabs.mdx index 75d639c28..262291d28 100644 --- a/components/tabs.mdx +++ b/components/tabs.mdx @@ -1,7 +1,7 @@ --- title: "Tabs" description: "Toggle content using the Tabs component" -icon: 'panel-top' +icon: "panel-top" --- Use tabs to organize content into multiple panels that users can switch between. You can add any number of tabs and include other components inside each tab. @@ -26,9 +26,7 @@ Use tabs to organize content into multiple panels that users can switch between. - - -````mdx Tabs Example +````mdx Tabs example ☝️ Welcome to the content that you can only see inside the first Tab. @@ -49,10 +47,8 @@ Use tabs to organize content into multiple panels that users can switch between. ```` - - ## Properties - The title of the tab. Short titles are easier to navigate + The title of the tab. Short titles are easier to navigate. From 087fa4e8cc37c5ae6549073c42f79cfe22f32401 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:38:56 -0700 Subject: [PATCH 23/29] update migration --- guides/migration.mdx | 33 +++++++-------------------------- 1 file changed, 7 insertions(+), 26 deletions(-) diff --git a/guides/migration.mdx b/guides/migration.mdx index f568d5d9f..98d0b23c8 100644 --- a/guides/migration.mdx +++ b/guides/migration.mdx @@ -92,33 +92,14 @@ Don't see your documentation provider or have a custom system? We can still help ## Commands -- `mintlify-scrape section [url]` - Scrapes multiple pages in a site -- `mintlify-scrape page [url]` - Scrapes a single page in a site +- `mintlify-scrape section [url]` - Scrapes multiple pages in a site. +- `mintlify-scrape page [url]` - Scrapes a single page in a site. The commands automatically detect the framework. ## Installation -First, install the package: - -```bash -npm i @mintlify/scraping -``` - -### One-time use - - - -```bash Section -npx @mintlify/scraping@latest section [url] -``` - - -```bash Page -npx @mintlify/scraping@latest page [url] -``` - - +You can install the package globally or for one-time use. ### Global installation @@ -126,22 +107,22 @@ npx @mintlify/scraping@latest page [url] npm install @mintlify/scraping@latest -g ``` -### Global usage +### One-time use ```bash Section -mintlify-scrape section [url] +npx @mintlify/scraping@latest section [url] ``` ```bash Page -mintlify-scrape page [url] +npx @mintlify/scraping@latest page [url] ``` -### OpenAPI migration +## OpenAPI migration Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint. From 2ba4e5516f032b316fef00316b64040897793c8b Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:44:56 -0700 Subject: [PATCH 24/29] Update react-components.mdx --- react-components.mdx | 46 +++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/react-components.mdx b/react-components.mdx index 7017f1a25..336f0c501 100644 --- a/react-components.mdx +++ b/react-components.mdx @@ -7,15 +7,17 @@ icon: "react" import { Counter } from "/snippets/counter.mdx"; import { ColorGenerator } from "/snippets/color-generator.jsx"; -[React components](https://react.dev) are a powerful way to create interactive and reusable elements in your documentation. Use React directly in your MDX files without any additional setup. +[React components](https://react.dev) are a powerful way to create interactive and reusable elements in your documentation. -## Using React Components +You can use React components directly in your `MDX` files without any additional setup. + +## Using React components You can build components directly in your MDX files using [React hooks](https://react.dev/reference/react/hooks). -### Basic Example +### Basic example -Here's a basic example of a counter component: +Here is a basic example of a counter component: ```mdx export const Counter = () => { @@ -32,17 +34,17 @@ export const Counter = () => { } ``` -Use the `Counter` component in your MDX files like this: +The `Counter` component can be used in your `MDX` files like this: ```mdx ``` -The component renders as an interactive React component in the MDX file. +The counter renders as an interactive React component. -## Importing Components +## Importing components Just like in regular React, you can import components from other files. @@ -51,10 +53,10 @@ import { ColorGenerator } from "/snippets/color-generator.jsx" ``` - Unlike regular React, you can't import components from every MDX file. Reusable components can only be referenced from MDX files within the `snippets` folder. + Unlike regular React, you can't import components from every `MDX` file. Reusable components can only be referenced from `MDX` files within the `snippets` folder. -After importing the component, use it in your MDX files like this: +After importing the component, use it in your `MDX` files like this: ```mdx @@ -62,9 +64,9 @@ After importing the component, use it in your MDX files like this: Learn more about [reusable snippets](/reusable-snippets). -### Complex Example +### Complex example -You can build much more complex components. Here's an example of a color generator component that uses multiple React hooks: +You can build much more complex components. Here is an example of a color generator component that uses multiple React hooks: ```mdx /snippets/color-generator.jsx [expandable] export const ColorGenerator = () => { @@ -179,30 +181,30 @@ export const ColorGenerator = () => { } ``` -Use the above component in your MDX files like this: +The `ColorGenerator` component can be used in your `MDX` files like this: ```mdx ``` -The component renders as an interactive React component in the MDX file. +The color generator renders as an interactive React component. ## Considerations - + React hook components render on the client-side, which has several implications: - - **SEO**: Search engines might not fully index dynamic content - - **Initial Load**: Visitors may experience a flash of loading content before components render - - **Accessibility**: Ensure dynamic content changes are announced to screen readers + - **SEO**: Search engines might not fully index dynamic content. + - **Initial load**: Visitors may experience a flash of loading content before components render. + - **Accessibility**: Ensure dynamic content changes are announced to screen readers. - - - **Optimize dependency arrays**: Include only necessary dependencies in your `useEffect` dependency arrays - - **Memoize complex calculations**: Use `useMemo` or `useCallback` for expensive operations - - **Reduce re-renders**: Break large components into smaller ones to prevent cascading re-renders - - **Lazy loading**: Consider lazy loading complex components to improve initial page load time + + - **Optimize dependency arrays**: Include only necessary dependencies in your `useEffect` dependency arrays. + - **Memoize complex calculations**: Use `useMemo` or `useCallback` for expensive operations. + - **Reduce re-renders**: Break large components into smaller ones to prevent cascading re-renders. + - **Lazy loading**: Consider lazy loading complex components to improve initial page load time. From ef5cc6f8a9d2760c58ca951578787e01bbfd158c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:46:31 -0700 Subject: [PATCH 25/29] Update broken-links.mdx --- settings/broken-links.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/settings/broken-links.mdx b/settings/broken-links.mdx index 22b52f849..13bda8396 100644 --- a/settings/broken-links.mdx +++ b/settings/broken-links.mdx @@ -1,12 +1,12 @@ --- title: "Redirects and broken links" description: "Tools to help prevent invalid links" -icon: 'link-2' +icon: "link-2" --- When you change the path of a file in your docs folder, it also changes the URL path to that page. This may happen when restructuring your docs or changing the sidebar title. -## Broken Links +## Broken links Catch broken links with our CLI. [Install the CLI](/installation) and run the command: From 6c073cfc63cc4d76f3802052c45bc6f73b78b5ad Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 16:48:32 -0700 Subject: [PATCH 26/29] Update overview.mdx --- integrations/support/overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/integrations/support/overview.mdx b/integrations/support/overview.mdx index 442447e14..c3e13bfbc 100644 --- a/integrations/support/overview.mdx +++ b/integrations/support/overview.mdx @@ -35,7 +35,7 @@ horizontal -## Enabling Support Integrations +## Enabling support integrations Integrate customer support widgets into your documentation. Add the `integrations` field to your `docs.json` file with your respective app ID. @@ -46,4 +46,4 @@ Integrate customer support widgets into your documentation. Add the `integration } ``` -To request a customer support integration, let us know in [our community](https://join.slack.com/t/mintlify-users/shared_invite/zt-1xfzz6x35-f4o4WCYfpvLhSj3O7WAOMA). +Request a new customer support integration in [our Slack community](https://join.slack.com/t/mintlify-users/shared_invite/zt-1xfzz6x35-f4o4WCYfpvLhSj3O7WAOMA). From a9f0e3edf96215d149a253b10931df6ae616092b Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 17:03:21 -0700 Subject: [PATCH 27/29] Update ci.mdx --- settings/ci.mdx | 335 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 316 insertions(+), 19 deletions(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index 3e0a59ebd..8cfd66414 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -8,7 +8,7 @@ icon: "circle-check" CI checks are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=docs-ci), an add-on for other plans, and for GitHub. -Use CI checks to lint your docs for errors and provide warnings before you deploy. +Use CI checks to lint your docs for errors and provide warnings before you deploy. CI checks are configured to run on commits to your configured deployment branch, or on pull requests against that branch. ## Installation @@ -18,28 +18,20 @@ For GitHub Apps, you can choose to give permissions to only a single repository. ## Configuration -Configure the CI checks enabled for a deployment on the Mintlify dashboard by navigating to the 'Add-Ons' tab. There you can enable or disable the checks you'd like to run. +Configure the CI checks enabled for a deployment by navigating to the [Add-ons](https://dashboard.mintlify.com/products/addons) page of your dashboard. Enable the checks that you want to run. When enabling checks, you can choose to run them at a `Warning` or `Blocking` level. - +- A `Warning` level check will never provide a failure status, even if there is an error or suggestions. +- A `Blocking` level check will provide a failure status if not passed, or changes are suggested. +## Available CI checks -A `Blocking` level check will provide a failure status if not passed, or changes are suggested.
+### Broken links -A `Warning` level check will never provide a failure status, even if there is an error or suggestions. +Similar to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, we automatically check your docs for broken links. - - -## When Do They Run? - -CI checks are configured to run on commits to your configured deployment branch, or on pull requests against that branch. - -## Available CI Checks - -### Broken Links - -Similar to how the [CLI link checker](/settings/broken-links#broken-links) works on your local machine, we automatically check your docs for broken links. To see the results of this check, visit GitHub's check results page for a specific commit. +To see the results of this check, visit GitHub's check results page for a specific commit. ### Vale @@ -50,7 +42,312 @@ Mintlify supports automatically running Vale in a CI check and displaying the re #### Configuration If you have a `.vale.ini` file in the root content directory for your deployment, we automatically use that configuration file. We also automatically use any configuration files in your specified `stylesPath`. -Don't have a Vale config or not sure where to get started? Don't worry, Mintlify has a default configuration that automatically loads if one is not provided. +If you do not have a Vale config file, the default configuration automatically loads. + +````mdx Default vale.ini configuration expandable +# Top level styles +StylesPath = /app/styles +MinAlertLevel = suggestion +IgnoredScopes = code, tt, img, url, a +SkippedScopes = script, style, pre, figure, code + +# Vocabularies +Vocab = Mintlify + +# This is required since Vale doesn't officially support MDX +[formats] +mdx = md + +# MDX support +[*.mdx] +BasedOnStyles = Vale +Vale.Terms = NO # Enforces really harsh capitalization rules, keep off + +# `import ...`, `export ...` +# `` +# `...` +# `{ ... }` +TokenIgnores = (?sm)((?:import|export) .+?$), \ +(?)(?!`), \ +(<[A-Z]\w+>.+?<\/[A-Z]\w+>) + +# Exclude: +# `` +BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ +(?sm)^({.+.*}) + +CommentDelimiters = {/*, */} +```` + +```text Default Vale vocabulary expandable +Mintlify +mintlify +VSCode +openapi +OpenAPI +Github +APIs + +repo +npm +dev + +Lorem +ipsum +impsum +amet + +const +myName +myObject +bearerAuth +favicon +topbar +url +borderRadius +args +modeToggle +ModeToggle +isHidden +autoplay + +_italic_ +Strikethrough +Blockquotes +Blockquote +Singleline +Multiline + +onboarding + +async +await +boolean +enum +func +impl +init +instanceof +typeof +params +stdin +stdout +stderr +stdout +stdin +var +const +let +null +undefined +struct +bool + +cors +csrf +env +xhr +xhr2 +jwt +oauth +websocket +localhost +middleware +runtime +webhook +stdin +stdout + +json +yaml +yml +md +txt +tsx +jsx +css +scss +html +png +jpg +svg + +cdn +cli +css +dom +dto +env +git +gui +http +https +ide +jvm +mvc +orm +rpc +sdk +sql +ssh +ssl +tcp +tls +uri +url +ux +ui + +nodejs +npm +yarn +pnpm +eslint +pytest +golang +rustc +kubectl +mongo +postgres +redis + +JavaScript +TypeScript +Python +Ruby +Rust +Go +Golang +Java +Kotlin +Swift +Node.js +NodeJS +Deno + +React +Vue +Angular +Next.js +Nuxt +Express +Django +Flask +Spring +Laravel +Redux +Vuex +TensorFlow +PostgreSQL +MongoDB +Redis +PNPM + +Docker +Kubernetes +AWS +Azure +GCP +Terraform +Jenkins +CircleCI +GitLab +Heroku + +Git +git +GitHub +GitLab +Bitbucket +VSCode +Visual Studio Code +IntelliJ +WebStorm +ESLint +eslint +Prettier +prettier +Webpack +webpack +Vite +vite +Babel +babel +Jest +jest +Mocha +Cypress +Postman + +HTTP +HTTPS +OAuth +JWT +GraphQL +REST +WebSocket +TCP/IP + +NPM +Yarn +PNPM +Pip +PIP +Cargo +RubyGems + +Swagger +OpenAPI +Markdown +MDX +Storybook +TypeDoc +JSDoc + +MySQL +PostgreSQL +MongoDB +Redis +Elasticsearch +DynamoDB + +Linux +Unix +macOS +iOS + +Firefox +Chromium +WebKit + +config +ctx +desc +dir +elem +err +len +msg +num +obj +prev +proc +ptr +req +res +str +tmp +val +vars + +todo +href +lang +nav +prev +next +toc +``` Please note that for security reasons, we are unable to support any absolute `stylesPath`, or `stylesPath` which include `..` values. Please use relative paths and include the `stylesPath` in your repository. @@ -66,8 +363,8 @@ For packages not included in your repository, you may specify any packages from Please note that for security reasons, we are unable to support automatically downloading packages that are not from the [Vale package registry](https://vale.sh/explorer). -#### Vale with MDX -Vale does not natively support MDX, but Vale's author has provided a [custom extension](https://github.com/errata-ai/MDX) to support it. +#### Vale with `MDX` +Vale does not natively support `MDX`, but Vale's author has provided a [custom extension](https://github.com/errata-ai/MDX) to support it. If you prefer not to use this extension, we recommend the following lines in your `.vale.ini` file: ```ini From 6337d753c418f8c5a21c311ac17dd3a73501b596 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 14 Jul 2025 17:09:42 -0700 Subject: [PATCH 28/29] Document style preferences learned from content refresh project MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add detailed style guide based on patterns identified during DOC-84 content refresh work, including: - Heading and formatting conventions - Component introduction patterns - Property description standards - Language and tone preferences - Code example best practices - Content organization principles These learnings will help maintain consistency in future documentation updates. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/CLAUDE.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 213dd1250..6f2f6408c 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -34,6 +34,41 @@ - Use broadly applicable examples rather than overly specific business cases - Lead with context when helpful - explain what something is before diving into implementation details +### Style preferences (learned from content refresh project) +#### Headings and formatting +- Use sentence case for all headings ("Getting started", not "Getting Started") +- Use "Properties" instead of "Props" for component documentation +- Use sentence case for code block titles ("Expandable example", not "Expandable Example") + +#### Component introductions +- Start with action-oriented language: "Use [component] to..." rather than "The [component] component..." +- Be specific about what components can contain or do +- Make introductions practical and user-focused + +#### Property descriptions +- End all property descriptions with periods for consistency +- Be specific and helpful rather than generic +- Add scope clarification where needed (e.g., "For Font Awesome icons only:") +- Use proper technical terminology ("boolean" not "bool") + +#### Language and tone +- Prefer active voice and direct language +- Remove unnecessary words while maintaining clarity +- Use "you complete" over "completing" for more direct communication +- Break complex instructions into clear numbered steps +- Make language more precise and contextual + +#### Code examples +- Keep examples simple and practical +- Use consistent formatting and naming +- Provide clear, actionable examples rather than showing multiple options when one will do + +#### Content organization +- Structure content in the order users need it +- Combine related information to reduce redundancy +- Use specific links (direct to relevant pages rather than generic dashboards) +- Put most commonly needed information first + ## Git workflow - NEVER use --no-verify when committing - Ask how to handle uncommitted changes before starting From bde91ac55c480f1a7d325b4835431368e920c681 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 15 Jul 2025 09:37:11 -0700 Subject: [PATCH 29/29] add reviewer feedback --- settings/ci.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/ci.mdx b/settings/ci.mdx index 8cfd66414..d507d2e36 100644 --- a/settings/ci.mdx +++ b/settings/ci.mdx @@ -5,7 +5,7 @@ icon: "circle-check" --- - CI checks are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=docs-ci), an add-on for other plans, and for GitHub. + CI checks are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=docs-ci), as an add-on for other plans, and only for GitHub. Use CI checks to lint your docs for errors and provide warnings before you deploy. CI checks are configured to run on commits to your configured deployment branch, or on pull requests against that branch.