From f64c17d45b3a0e910f79222313a6548c2de37e7f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:23:16 +0000 Subject: [PATCH 01/41] Update quickstart.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- quickstart.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index bc56bad0b..f395e1800 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -4,13 +4,9 @@ description: "Deploy your documentation site and make your first change." keywords: ["quickstart", "deploy", "get started", "first steps", "tutorial", "setup", "onboarding"] --- -After you complete this guide, you'll have a live documentation site ready to customize and update. - ## Before you begin -Mintlify uses a docs-as-code approach to manage your documentation. Every page on your site has a corresponding file stored in your documentation repository. - -When you connect your documentation repository to your Mintlify deployment, you can work on your documentation locally or in the web editor and sync any changes to your remote repository. +Mintlify uses a docs-as-code approach. Every page has a corresponding file in your documentation repository. ## Deploy your documentation site From 0a94e792e0ee453e665b8c29b0e63f08e4294ca4 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:23:23 +0000 Subject: [PATCH 02/41] Update quickstart.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- quickstart.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index f395e1800..6fd36801e 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -10,9 +10,7 @@ Mintlify uses a docs-as-code approach. Every page has a corresponding file in yo ## Deploy your documentation site -Go to [mintlify.com/start](https://mintlify.com/start) and complete the onboarding process. During onboarding, you'll connect your GitHub account, create or select a repository for your documentation, and install the GitHub App to enable automatic deployments. - -After onboarding, your documentation site is deployed and accessible at your `.mintlify.app` URL. +Go to [mintlify.com/start](https://mintlify.com/start) and complete onboarding. You'll connect GitHub, select a repository, and install the GitHub App for automatic deployments. From f5752ee1a948a0204d8f67ca445fda412c411e5c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:23:31 +0000 Subject: [PATCH 03/41] Update quickstart.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- quickstart.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index 6fd36801e..4bf0b3307 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -14,9 +14,7 @@ Go to [mintlify.com/start](https://mintlify.com/start) and complete onboarding. - If you want to get started quickly without connecting your own repository, you can skip the GitHub connection during onboarding. Mintlify creates a private repository in a private organization and automatically configures the GitHub App for you. - - This lets you use the web editor immediately and migrate to your own repository later. + Skip GitHub connection to start quickly. Mintlify creates a private repository and configures the GitHub App automatically. Migrate to your own repository later. From 2d19b24a52f2f14bdf7c25fcac8f1b3e72527cf8 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:23:37 +0000 Subject: [PATCH 04/41] Update quickstart.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- quickstart.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index 4bf0b3307..850152e64 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -20,9 +20,7 @@ Go to [mintlify.com/start](https://mintlify.com/start) and complete onboarding. ## View your deployed site -Your documentation site is now deployed at `https://.mintlify.app`. - -Find your exact URL on the **Overview** page of your [dashboard](https://dashboard.mintlify.com/). +Your site is deployed at `https://.mintlify.app`. Find your URL on the **Overview** page of your [dashboard](https://dashboard.mintlify.com/). Date: Tue, 3 Feb 2026 20:23:43 +0000 Subject: [PATCH 05/41] Update quickstart.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quickstart.mdx b/quickstart.mdx index 850152e64..e5924bd80 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -37,7 +37,7 @@ Your site is deployed at `https://.mintlify.app`. Find your U - Your site is ready to view immediately. Use this URL for testing and sharing with your team. Before sharing with your users, you may want to add a [custom domain](/customize/custom-domain). + Use this URL for testing and team sharing. Add a [custom domain](/customize/custom-domain) before sharing with users. ## Make your first change From d6226b536dc45c349913a076418c5d59ca40c685 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:23:51 +0000 Subject: [PATCH 06/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/installation.mdx b/installation.mdx index 4abf2e3da..a1554a903 100644 --- a/installation.mdx +++ b/installation.mdx @@ -15,9 +15,7 @@ keywords: ["CLI", "npm", "local development", "Node.js"] alt="Decorative graphic representing the CLI." /> -Use the [CLI](https://www.npmjs.com/package/mint) to preview your documentation locally as you write and edit. View changes in real-time before deploying, test your documentation site's appearance and functionality, and catch issues like broken links or accessibility problems. - -The CLI also has utilities for maintaining your documentation, including commands to rename files, validate OpenAPI specifications, and migrate content between formats. +Use the [CLI](https://www.npmjs.com/package/mint) to preview documentation locally, view changes in real-time, and catch issues like broken links or accessibility problems. The CLI also includes utilities for renaming files, validating OpenAPI specs, and migrating content. ## Prerequisites From 709ba5904ed7284c4c12335c02d5e861bc8f7f29 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:24:00 +0000 Subject: [PATCH 07/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/installation.mdx b/installation.mdx index a1554a903..0bc0c8861 100644 --- a/installation.mdx +++ b/installation.mdx @@ -27,9 +27,8 @@ Use the [CLI](https://www.npmjs.com/package/mint) to preview documentation local - 1. Go to the [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard. - 2. Note your repository location. It is one of these formats: - - `mintlify-community/docs-{org-name}-{id}` (Mintlify-hosted repository) + Find your repository on the [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page: + - `mintlify-community/docs-{org-name}-{id}` (Mintlify-hosted) - `your-org/your-repo` (your own GitHub repository) From 942912db7ca15e54e5b9f64414b2fbfcf93ac11b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:24:11 +0000 Subject: [PATCH 08/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/installation.mdx b/installation.mdx index 0bc0c8861..542c3f951 100644 --- a/installation.mdx +++ b/installation.mdx @@ -35,7 +35,7 @@ Use the [CLI](https://www.npmjs.com/package/mint) to preview documentation local - Replace `your-org/your-repo` with your actual repository details from [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings). + Replace `your-org/your-repo` with your repository from [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings). ```bash git clone https://github.com/your-org/your-repo @@ -43,14 +43,12 @@ Use the [CLI](https://www.npmjs.com/package/mint) to preview documentation local ``` - **GitHub App required.** To enable automatic deployments when you push changes, you must install the GitHub app. See [GitHub](/deploy/github) for more information. + Install the [GitHub app](/deploy/github) to enable automatic deployments. - You can clone your repository as a private or public repository. Public repositories are visible to anyone who navigates to the repository URL. Private repositories are only visible to people in your organization. - - On the [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard, select **Clone as private** or **Clone as public**. + On the [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page, select **Clone as private** or **Clone as public**. From 7f415ac48210fc62022df387c21043814f44ed96 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:24:19 +0000 Subject: [PATCH 09/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/installation.mdx b/installation.mdx index 542c3f951..86c912f09 100644 --- a/installation.mdx +++ b/installation.mdx @@ -86,17 +86,13 @@ npx mint dev ### Custom ports -By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command: +Customize the port with the `--port` flag: ```bash mint dev --port 3333 ``` -If you attempt to run on a port that is already in use, the CLI uses the next available port: - -```mdx -Port 3000 is already in use. Trying 3001 instead. -``` +If a port is in use, the CLI uses the next available port. ## Skip OpenAPI processing From e61ef7351028cd8ea31c77e32c1d2091ad063b95 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:24:28 +0000 Subject: [PATCH 10/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/installation.mdx b/installation.mdx index 86c912f09..ad0fb5596 100644 --- a/installation.mdx +++ b/installation.mdx @@ -96,7 +96,7 @@ If a port is in use, the CLI uses the next available port. ## Skip OpenAPI processing -If you have many OpenAPI files, skip OpenAPI file processing during local development to improve performance by using the `--disable-openapi` flag: +Skip OpenAPI processing to improve performance: ```bash mint dev --disable-openapi @@ -104,9 +104,7 @@ mint dev --disable-openapi ### Preview as a specific group -If you use group-based access control to restrict access to your documentation, you can preview as a specific authentication group by using the `--groups [groupname]` flag. - -For example, if you have a group named `admin`, you can preview as a member of that group with the command: +Preview as a specific authentication group: ```bash mint dev --groups admin From 6f469ce2aec958f280804984534a436b8bc39e20 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:24:36 +0000 Subject: [PATCH 11/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/installation.mdx b/installation.mdx index ad0fb5596..214c24417 100644 --- a/installation.mdx +++ b/installation.mdx @@ -112,19 +112,19 @@ mint dev --groups admin ## Create a new project -To create a new documentation project, run the following command: +Create a new documentation project: ```bash mint new [directory] ``` -This command clones the [starter kit](https://github.com/mintlify/starter) into a specified directory. If you do not specify a directory, the CLI tool prompts you to create a new subdirectory or overwrite the current directory. +This clones the [starter kit](https://github.com/mintlify/starter). Without a directory, the CLI prompts you to create a subdirectory or overwrite the current directory. - Overwriting the current directory deletes any existing files. + Overwriting the current directory deletes existing files. -The CLI tool prompts you for a project name and [theme](/customize/themes) to finish setting up your project. +The CLI prompts for a project name and [theme](/customize/themes). ### Flags From 246300eaf9fd506613d118bd8149758248ac136b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:24:44 +0000 Subject: [PATCH 12/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/installation.mdx b/installation.mdx index 214c24417..5a29e12bb 100644 --- a/installation.mdx +++ b/installation.mdx @@ -134,10 +134,10 @@ The CLI prompts for a project name and [theme](/customize/themes). | `--theme` | Set the [theme](/customize/themes) of the new project. | Yes | | `--force` | Overwrite the current directory without prompting, even if it contains existing files. | No | -When running `mint new` in non-interactive environments like CI/CD pipelines or with AI coding agents, you must provide all required flags (`--name` and `--theme`). +In non-interactive environments (CI/CD, AI agents), provide all required flags (`--name` and `--theme`). - The CLI automatically detects non-interactive environments. If required flags are missing, it outputs usage instructions instead of hanging on prompts. + The CLI detects non-interactive environments and outputs usage instructions if flags are missing. ## Update the CLI From 138396b093c1f367f239578e214201537db51dae Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:24:51 +0000 Subject: [PATCH 13/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/installation.mdx b/installation.mdx index 5a29e12bb..b938f4583 100644 --- a/installation.mdx +++ b/installation.mdx @@ -142,13 +142,13 @@ In non-interactive environments (CI/CD, AI agents), provide all required flags ( ## Update the CLI -If your local preview is out of sync with what you see on the web in the production version, update your local CLI: +Update the CLI if your local preview is out of sync: ```bash mint update ``` -If this `mint update` command is not available on your local version, re-install the CLI with the latest version: +If `mint update` is unavailable, reinstall the CLI: ```bash npm From c18fdb718a411f5953c1809c6fbd2e197eafcd5f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:25:00 +0000 Subject: [PATCH 14/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/installation.mdx b/installation.mdx index b938f4583..fbe7f9bd6 100644 --- a/installation.mdx +++ b/installation.mdx @@ -164,17 +164,17 @@ If `mint update` is unavailable, reinstall the CLI: ### Find broken links -Identify any broken internal links with the following command: +Identify broken internal links: ```bash mint broken-links ``` -The command ignores files matching [.mintignore](/organize/mintignore) patterns. Links that point to ignored files are reported as broken. +Files matching [.mintignore](/organize/mintignore) patterns are ignored. Links to ignored files are reported as broken. ### Find accessibility issues -Test the color contrast ratios and search for missing alt text on images and videos in your documentation with the following command: +Test color contrast and missing alt text: ```bash mint a11y From 69c21d394be33c90d52997d0977714bd19b83e1d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:25:05 +0000 Subject: [PATCH 15/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/installation.mdx b/installation.mdx index fbe7f9bd6..961b7ff52 100644 --- a/installation.mdx +++ b/installation.mdx @@ -192,7 +192,7 @@ mint a11y --skip-alt-text ### Validate documentation build -Validate your documentation build in strict mode, which exits with an error if there are any warnings or errors. Use this command for CI/CD pipelines to prevent broken documentation deployments. +Validate in strict mode (exits with error on warnings). Use in CI/CD to prevent broken deployments. ```bash mint validate From fc8ba9a999029b42953b67cd17be08eaf997653b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:25:12 +0000 Subject: [PATCH 16/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/installation.mdx b/installation.mdx index 961b7ff52..ff29b39f2 100644 --- a/installation.mdx +++ b/installation.mdx @@ -205,13 +205,13 @@ Use flags to configure the validation command. ### Check OpenAPI spec -Check your OpenAPI file for errors with the following command: +Check your OpenAPI file for errors: ```bash mint openapi-check ``` -Pass a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`). +Pass a filename (`./openapi.yaml`) or URL (`https://petstore3.swagger.io/api/v3/openapi.json`). ### Rename files From dd41d3f313b449dc82411177e24fabf7117412c6 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:25:21 +0000 Subject: [PATCH 17/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/installation.mdx b/installation.mdx index ff29b39f2..5cb56cad5 100644 --- a/installation.mdx +++ b/installation.mdx @@ -215,7 +215,7 @@ Pass a filename (`./openapi.yaml`) or URL (`https://petstore3.swagger.io/api/v3/ ### Rename files -Rename and update all references to files with the following command: +Rename and update all references: ```bash mint rename @@ -223,13 +223,13 @@ mint rename ### Migrate MDX endpoint pages -Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command: +Migrate MDX endpoint pages to autogenerated pages: ```bash mint migrate-mdx ``` -This command converts individual MDX endpoint pages to autogenerated pages defined in your `docs.json`, moves MDX content to the `x-mint` extension in your OpenAPI specification, and updates your navigation. See [Migrating from MDX](/guides/migrating-from-mdx) for detailed information. +Converts MDX endpoint pages to autogenerated pages, moves content to the `x-mint` extension, and updates navigation. See [Migrating from MDX](/guides/migrating-from-mdx). ## Formatting From 9576883dc10bcf28f05ac324a3f983851b540068 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:25:31 +0000 Subject: [PATCH 18/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/installation.mdx b/installation.mdx index 5cb56cad5..62cb8c770 100644 --- a/installation.mdx +++ b/installation.mdx @@ -233,11 +233,10 @@ Converts MDX endpoint pages to autogenerated pages, moves content to the `x-mint ## Formatting -While developing locally, we recommend using extensions in your IDE to recognize and format MDX files. +Use IDE extensions for MDX: -If you use Cursor, Windsurf, or VS Code, we recommend the [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. - -If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting. +- **Cursor/Windsurf/VS Code**: [MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) +- **JetBrains**: [MDX plugin](https://plugins.jetbrains.com/plugin/14944-mdx) and [Prettier](https://prettier.io/docs/webstorm) ## Troubleshooting From 4d20c9d70884a4e6962333de72f323b2232521c9 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:25:43 +0000 Subject: [PATCH 19/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/installation.mdx b/installation.mdx index 62cb8c770..1dc483f1e 100644 --- a/installation.mdx +++ b/installation.mdx @@ -242,24 +242,16 @@ Use IDE extensions for MDX: - This may be due to an outdated version of node. Try the following: - - 1. Remove the currently-installed version of the mint CLI: `npm uninstall -g mint` - 2. Upgrade to Node.js. - 3. Reinstall the mint CLI: `npm install -g mint` + Outdated Node.js version. Uninstall CLI (`npm uninstall -g mint`), upgrade Node.js, then reinstall (`npm install -g mint`). - **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again. + Delete `~/.mintlify` folder and run `mint dev` again. - This is due to not having the required permissions to globally install node packages. - - **Solution**: Try running `sudo npm i -g mint`. You will be prompted for your password, which is the one you use to unlock your computer. + Missing permissions for global install. Run `sudo npm i -g mint`. - This is likely due to an outdated version of the CLI. - - **Solution:** Run `mint update` to get the latest changes. + Outdated CLI. Run `mint update`. If you have any problems with the CLI package, you should first run `npm ls -g`. This command shows what packages are globally installed on your machine. From 6085960b786a61b3aa98bddcb3af8ca358eb469b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:25:56 +0000 Subject: [PATCH 20/41] Update installation.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- installation.mdx | 21 ++++----------------- 1 file changed, 4 insertions(+), 17 deletions(-) diff --git a/installation.mdx b/installation.mdx index 1dc483f1e..956b8b5f9 100644 --- a/installation.mdx +++ b/installation.mdx @@ -254,28 +254,15 @@ Use IDE extensions for MDX: Outdated CLI. Run `mint update`. - If you have any problems with the CLI package, you should first run `npm ls -g`. This command shows what packages are globally installed on your machine. - - If you don't use npm or don't see it in the -g list, try `which mint` to locate the installation. - - If you have a package named `mint` and a package named `mintlify` installed, you should uninstall `mintlify`. + If both `mint` and `mintlify` are installed, uninstall `mintlify`: - 1. Uninstall the old package: - ```bash - npm uninstall -g mintlify - ``` - 2. Clear your npm cache: - ```bash - npm cache clean --force - ``` - 3. Reinstall the new package: ```bash + npm uninstall -g mintlify + npm cache clean --force npm i -g mint ``` - If you run `mint version` and the client version displays as `none`, the CLI may be unable to download the client application due to a corporate firewall or VPN blocking the download. - - **Solution:** Ask your IT administrator to whitelist `releases.mintlify.com` to enable local development with the CLI. + Firewall or VPN blocking download. Ask IT to whitelist `releases.mintlify.com`. From f5cf3037c7dd89c0e65d28958039987cab581ac7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:26:03 +0000 Subject: [PATCH 21/41] Update agent/index.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- agent/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agent/index.mdx b/agent/index.mdx index 9b20028fd..d82b00b75 100644 --- a/agent/index.mdx +++ b/agent/index.mdx @@ -8,7 +8,7 @@ keywords: ["automation", "automate", "AI", "autoupdate", "maintenance"] The agent is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=agent) for anyone with access to your dashboard. -The agent creates pull requests with proposed changes to your documentation based on your prompts. When you send a request to the agent, it references your documentation, connected repositories, and Slack messages to create content that follows technical writing best practices and adheres to the Mintlify schema. +The agent creates pull requests with proposed documentation changes. It references your docs, repositories, and Slack messages to create content following technical writing best practices and the Mintlify schema. ## What you can do with the agent From db5b41e430f53473018f249856de339ee32046e2 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:26:10 +0000 Subject: [PATCH 22/41] Update editor/index.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- editor/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editor/index.mdx b/editor/index.mdx index 251c69058..7018c3c93 100644 --- a/editor/index.mdx +++ b/editor/index.mdx @@ -17,7 +17,7 @@ keywords: ["editor", "visual", "gitbook"] alt="Decorative image in dark mode" /> -Create, edit, and publish documentation directly in your browser with the web editor. View and share previews of your changes; manage your site's navigation structure with drag-and-drop components; and publish updates using your team's preferred workflow. +Create, edit, and publish documentation in your browser. View and share previews, manage navigation with drag-and-drop, and publish using your team's workflow. ## Key features From 897c38f024066eaf29e6fb23f205da09441d2eda Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:26:15 +0000 Subject: [PATCH 23/41] Update components/index.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- components/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/index.mdx b/components/index.mdx index ab4064281..1e79e9557 100644 --- a/components/index.mdx +++ b/components/index.mdx @@ -5,7 +5,7 @@ keywords: ["MDX components", "documentation components", "UI components", "components"] --- -Mintlify provides built-in MDX components for your documentation pages. Use these components to structure content, draw attention to important information, document APIs, and guide navigation. +Built-in MDX components for structuring content, highlighting information, documenting APIs, and guiding navigation. ## Structure your content From a9f524ddcfa6afa58fee357bebff3cd4052d2586 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:26:21 +0000 Subject: [PATCH 24/41] Update api-playground/overview.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- api-playground/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 2e1ed8077..c0a132539 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -6,7 +6,7 @@ keywords: ["interactive", "API", "endpoint testing", "live API requests", "reque ## Overview -The API playground is an interactive environment that lets users test and explore your API endpoints. Developers can craft API requests, submit them, and view responses without leaving your documentation. +The API playground lets users test and explore endpoints. Craft requests, submit them, and view responses without leaving your documentation. See [Trigger an update](/api/update/trigger) for an example of the API playground in action. From 3f511d112632b0fae187fd28e6379f3ec31ba4c1 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:26:29 +0000 Subject: [PATCH 25/41] Update api-playground/overview.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- api-playground/overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index c0a132539..61664a974 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -15,9 +15,9 @@ See [Trigger an update](/api/update/trigger) for an example of the API playgroun API playground for the trigger an update endpoint. -The playground generates interactive pages for your endpoints based on your OpenAPI specification or AsyncAPI schema. If you modify your API, the playground automatically updates the relevant pages. +The playground generates interactive pages from your OpenAPI or AsyncAPI spec. Updates automatically when you modify your API. -We recommend generating your API playground from an OpenAPI specification. However, you can manually create API reference pages after defining a base URL and authentication method in your `docs.json`. +Generate from an OpenAPI spec (recommended) or manually create pages after defining base URL and auth in `docs.json`. ## Get started From 68cb04a166d1eba8f2b45c75a7bc3db3eeba4066 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:26:37 +0000 Subject: [PATCH 26/41] Update api-playground/overview.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- api-playground/overview.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 61664a974..698f52e35 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -35,11 +35,11 @@ Generate from an OpenAPI spec (recommended) or manually create pages after defin - Update your `docs.json` to reference your OpenAPI specification. + Update `docs.json` to reference your OpenAPI spec. - **To automatically generate pages for all endpoints in your OpenAPI specification**, add an `openapi` property to any navigation element. + **To generate pages for all endpoints**, add an `openapi` property to any navigation element. - This example generates a page for each endpoint specified in `openapi.json` and organizes the pages in the "API reference" group. + This generates a page for each endpoint in `openapi.json`. ```json Generate all endpoint pages "navigation": { From 58bca4d6323e3e5c3af17abc282f5849db656dd5 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:26:43 +0000 Subject: [PATCH 27/41] Update api-playground/overview.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- api-playground/overview.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 698f52e35..de48e905c 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -52,9 +52,7 @@ Generate from an OpenAPI spec (recommended) or manually create pages after defin } ``` - **To generate pages for only specific endpoints**, list the endpoints in the `pages` property of the navigation element. - - This example generates pages for only the `GET /users` and `POST /users` endpoints. To generate other endpoint pages, add additional endpoints to the `pages` array. + **To generate pages for specific endpoints**, list them in the `pages` property. ```json Generate specific endpoint pages "navigation": { From 416ea8b1363ff515584bd8b4a7e21f3ec5f43d7f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:26:49 +0000 Subject: [PATCH 28/41] Update api-playground/overview.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- api-playground/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index de48e905c..0a86a5451 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -74,7 +74,7 @@ Generate from an OpenAPI spec (recommended) or manually create pages after defin ## Customize your playground -Customize your API playground by defining the following properties in your `docs.json`. +Define these properties in `docs.json`: Configurations for the API playground. From c2bf4b06588123fb555fef4a7fa9f735d8e9e619 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:26:56 +0000 Subject: [PATCH 29/41] Update api-playground/overview.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- api-playground/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 0a86a5451..b50fe1021 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -116,7 +116,7 @@ Define these properties in `docs.json`: ### Example configuration -This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown in the code snippets, and the playground prefills the request body with example values. +Interactive playground with cURL, Python, and JavaScript snippets. Shows only required parameters and prefills request body with examples. ```json { From b0512ac1a275b491ce95bfce98938da7c48ef190 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:27:02 +0000 Subject: [PATCH 30/41] Update api-playground/overview.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- api-playground/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index b50fe1021..d1d18fd71 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -135,7 +135,7 @@ Interactive playground with cURL, Python, and JavaScript snippets. Shows only re ### Auth-based playground display -Use the `auth` display mode to show the interactive playground only to authenticated users. This is useful when you want to let users view your API documentation publicly while restricting playground access to logged-in users. +Show the playground only to authenticated users. Useful for public docs with restricted playground access. When `display` is set to `auth`: - Authenticated users see the interactive playground. From 5c285797b27ecc0f13fd3dfde47ff7fceebf4a6d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:27:11 +0000 Subject: [PATCH 31/41] Update api-playground/overview.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- api-playground/overview.mdx | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index d1d18fd71..ae13bbde9 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -166,17 +166,11 @@ If the page has no `groups` property, all authenticated users see the interactiv ### Custom endpoint pages -When you need more control over your API documentation, use the `x-mint` extension in your OpenAPI specification or create individual MDX pages for your endpoints. +For more control, use the `x-mint` extension in your OpenAPI spec or create individual MDX pages. -Both options allow you to: +Both let you customize metadata, add content, and control playground behavior. -- Customize page metadata -- Add additional content like examples -- Control playground behavior per page - -The `x-mint` extension is recommended so that all of your API documentation is automatically generated from your OpenAPI specification and maintained in one file. - -Individual MDX pages are recommended for small APIs or when you want to experiment with changes on a per-page basis. +Use `x-mint` to maintain all API docs in one file (recommended). Use MDX pages for small APIs or per-page experimentation. ## Further reading From 52c6624ed6989061d152a5bdb68d656919936187 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:27:20 +0000 Subject: [PATCH 32/41] Update guides/index.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/index.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/guides/index.mdx b/guides/index.mdx index 3b720298d..e15e3fb78 100644 --- a/guides/index.mdx +++ b/guides/index.mdx @@ -3,9 +3,7 @@ title: "Guides" description: "Learn how to create effective documentation with best practices and workflows." --- -The guides in this section contain advice for creating documentation that helps your users succeed. Whether you're starting from scratch or improving existing docs, these guides help you plan, write, and maintain your documentation. - -Above all else, consider your users' needs and goals. Document what helps them use your product and get back to their tasks. +Advice for creating documentation that helps users succeed. Plan, write, and maintain docs that address user needs and goals. ## Topics From 39fa37a7c7e9a795a71e44aa26a0f1f115547b41 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:27:25 +0000 Subject: [PATCH 33/41] Update guides/style-and-tone.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/style-and-tone.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx index 1de340339..ce6ef74c1 100644 --- a/guides/style-and-tone.mdx +++ b/guides/style-and-tone.mdx @@ -4,9 +4,7 @@ description: "Write effective technical documentation with consistent style." keywords: ["writing principles", "active voice", "technical writing", "style guides"] --- - - This page explains stylistic choices, common mistakes, and implementation tips for writing technical documentation. - + ## Writing principles From 443e69723f83fbcbb13adbaae22f6edaa6917f15 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:27:45 +0000 Subject: [PATCH 34/41] Update guides/style-and-tone.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/style-and-tone.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx index ce6ef74c1..cf4cea46d 100644 --- a/guides/style-and-tone.mdx +++ b/guides/style-and-tone.mdx @@ -8,7 +8,7 @@ keywords: ["writing principles", "active voice", "technical writing", "style gui ## Writing principles -- **Be concise.** People are reading documentation to achieve a goal. Get to the point quickly. +- **Be concise.** Get to the point quickly. - **Clarity over cleverness.** Be simple, direct, and avoid jargon or complex sentence structure. - **Use active voice.** Instead of saying "A configuration file should be created," use "Create a configuration file." - **Be skimmable.** Use headlines to orient readers. Break up text-heavy paragraphs. Use bullet points and lists to make it easier to scan. From 6f5015ead42b0cda09137e0ea2b3642bb03d7eb5 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:27:50 +0000 Subject: [PATCH 35/41] Update guides/style-and-tone.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/style-and-tone.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx index cf4cea46d..eafbaf4d2 100644 --- a/guides/style-and-tone.mdx +++ b/guides/style-and-tone.mdx @@ -9,7 +9,7 @@ keywords: ["writing principles", "active voice", "technical writing", "style gui ## Writing principles - **Be concise.** Get to the point quickly. -- **Clarity over cleverness.** Be simple, direct, and avoid jargon or complex sentence structure. +- **Clarity over cleverness.** Be simple and direct. Avoid jargon. - **Use active voice.** Instead of saying "A configuration file should be created," use "Create a configuration file." - **Be skimmable.** Use headlines to orient readers. Break up text-heavy paragraphs. Use bullet points and lists to make it easier to scan. - **Write in second person.** Referring to your reader makes it easier to follow instructions and makes the documentation feel more personal. From c6796af43b21d8060c3a3003b81bf2d2b1acdd57 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:27:59 +0000 Subject: [PATCH 36/41] Update guides/style-and-tone.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/style-and-tone.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx index eafbaf4d2..ca4b4370b 100644 --- a/guides/style-and-tone.mdx +++ b/guides/style-and-tone.mdx @@ -11,7 +11,7 @@ keywords: ["writing principles", "active voice", "technical writing", "style gui - **Be concise.** Get to the point quickly. - **Clarity over cleverness.** Be simple and direct. Avoid jargon. - **Use active voice.** Instead of saying "A configuration file should be created," use "Create a configuration file." -- **Be skimmable.** Use headlines to orient readers. Break up text-heavy paragraphs. Use bullet points and lists to make it easier to scan. +- **Be skimmable.** Use headlines, break up paragraphs, use lists. - **Write in second person.** Referring to your reader makes it easier to follow instructions and makes the documentation feel more personal. ## Common writing mistakes From 25b789bc2995450b2782a288fa6ecab6672d2acb Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:28:05 +0000 Subject: [PATCH 37/41] Update guides/style-and-tone.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/style-and-tone.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx index ca4b4370b..08ff38aa2 100644 --- a/guides/style-and-tone.mdx +++ b/guides/style-and-tone.mdx @@ -12,7 +12,7 @@ keywords: ["writing principles", "active voice", "technical writing", "style gui - **Clarity over cleverness.** Be simple and direct. Avoid jargon. - **Use active voice.** Instead of saying "A configuration file should be created," use "Create a configuration file." - **Be skimmable.** Use headlines, break up paragraphs, use lists. -- **Write in second person.** Referring to your reader makes it easier to follow instructions and makes the documentation feel more personal. +- **Write in second person.** Address the reader directly. ## Common writing mistakes From 5f31fb98743ebb4c3ada8ae0cb19518e1a49b6a3 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:28:22 +0000 Subject: [PATCH 38/41] Update guides/style-and-tone.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/style-and-tone.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx index 08ff38aa2..3c9e8ca4b 100644 --- a/guides/style-and-tone.mdx +++ b/guides/style-and-tone.mdx @@ -23,13 +23,13 @@ keywords: ["writing principles", "active voice", "technical writing", "style gui ## Tips for enforcing style -Leverage existing style guides to standardize your documentation: +Use existing style guides: - [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse) - [Google Developer Documentation Style Guide](https://developers.google.com/style) -When you know which writing principles you want to implement, automate as much as you can. You can use [CI checks](/deploy/ci) or linters like [Vale](https://vale.sh). +Automate with [CI checks](/deploy/ci) or linters like [Vale](https://vale.sh). ## Related pages From f6070ac270ac59877b5d567935d5a744edbfd958 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:28:28 +0000 Subject: [PATCH 39/41] Update guides/content-types.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/content-types.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/guides/content-types.mdx b/guides/content-types.mdx index 2c226ba00..60d88a8fe 100644 --- a/guides/content-types.mdx +++ b/guides/content-types.mdx @@ -4,11 +4,7 @@ description: "Choose the right content type for your documentation goals." keywords: ["Diátaxis", "tutorials", "how-tos", "reference", "explanation", "categorization"] --- - - This page explains different content types, when to use each one, and how to approach writing for each type. - - -Documentation should be organized around the specific goal you're trying to help people achieve. +Organize documentation around user goals. ## Categorize using the Diátaxis framework From 785a5c23be1ab09c1afe407707afb8a96b6743b7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:28:37 +0000 Subject: [PATCH 40/41] Update guides/content-types.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/content-types.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guides/content-types.mdx b/guides/content-types.mdx index 60d88a8fe..67360f93b 100644 --- a/guides/content-types.mdx +++ b/guides/content-types.mdx @@ -8,14 +8,14 @@ Organize documentation around user goals. ## Categorize using the Diátaxis framework -The [Diátaxis framework](https://diataxis.fr) is a helpful guide for categorizing content based on your audience's needs. Documentation can generally be mapped into one of these types: +The [Diátaxis framework](https://diataxis.fr) categorizes content by audience needs: -1. Tutorials: Learning-oriented content for new users -2. How-to guides: Task-oriented guidance for specific problems -3. Explanations: Understanding-oriented conceptual discussions -4. Reference: Information-oriented technical descriptions +1. **Tutorials**: Learning-oriented for new users +2. **How-to guides**: Task-oriented for specific problems +3. **Explanations**: Understanding-oriented conceptual discussions +4. **Reference**: Information-oriented technical descriptions -Defining content types helps you plan documentation with a clear purpose and makes it easier for users to find what they need. +Clear content types help users find what they need. A diagram of the Diátaxis framework showing four quadrants that correspond to the four content types: Tutorials, How-To Guides, Reference, and Explanation. From 956947bd131b571a22effdd0c8f433cace946246 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 20:28:44 +0000 Subject: [PATCH 41/41] Update guides/content-types.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> --- guides/content-types.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/guides/content-types.mdx b/guides/content-types.mdx index 67360f93b..14442b61b 100644 --- a/guides/content-types.mdx +++ b/guides/content-types.mdx @@ -36,13 +36,9 @@ Clear content types help users find what they need. ### Tutorials (Learning-oriented) -- **Audience goal**: Learn something new through step-by-step instructions. -- **Characteristics**: Sequential and assumes no prior knowledge. -- **Writing approach**: - - Set expectations of what the user will achieve after reading. - - Use clear, incremental steps. Minimize choices that need to be made by the user. - - Point out milestones along the way. - - Minimize theory and focus on concrete actions. +- **Goal**: Learn through step-by-step instructions +- **Characteristics**: Sequential, assumes no prior knowledge +- **Writing approach**: Set expectations, use clear incremental steps, minimize choices, point out milestones, focus on actions over theory ### How-To Guides (Problem-oriented)