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 diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 2e1ed8077..ae13bbde9 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. @@ -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 @@ -35,11 +35,11 @@ We recommend generating your API playground from an OpenAPI specification. Howev - 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": { @@ -52,9 +52,7 @@ We recommend generating your API playground from an OpenAPI specification. Howev } ``` - **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": { @@ -76,7 +74,7 @@ We recommend generating your API playground from an OpenAPI specification. Howev ## 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. @@ -118,7 +116,7 @@ Customize your API playground by defining the following properties in your `docs ### 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 { @@ -137,7 +135,7 @@ This example configures the API playground to be interactive with example code s ### 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. @@ -168,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. - -Both options allow you to: - -- Customize page metadata -- Add additional content like examples -- Control playground behavior per page +For more control, use the `x-mint` extension in your OpenAPI spec or create individual MDX pages. -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. +Both let you customize metadata, add content, and control playground behavior. -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 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 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 diff --git a/guides/content-types.mdx b/guides/content-types.mdx index 2c226ba00..14442b61b 100644 --- a/guides/content-types.mdx +++ b/guides/content-types.mdx @@ -4,22 +4,18 @@ 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 -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. @@ -40,13 +36,9 @@ Defining content types helps you plan documentation with a clear purpose and mak ### 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) 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 diff --git a/guides/style-and-tone.mdx b/guides/style-and-tone.mdx index 1de340339..3c9e8ca4b 100644 --- a/guides/style-and-tone.mdx +++ b/guides/style-and-tone.mdx @@ -4,17 +4,15 @@ 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 -- **Be concise.** People are reading documentation to achieve a goal. Get to the point quickly. -- **Clarity over cleverness.** Be simple, direct, and avoid jargon or complex sentence structure. +- **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. -- **Write in second person.** Referring to your reader makes it easier to follow instructions and makes the documentation feel more personal. +- **Be skimmable.** Use headlines, break up paragraphs, use lists. +- **Write in second person.** Address the reader directly. ## Common writing mistakes @@ -25,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 diff --git a/installation.mdx b/installation.mdx index 4abf2e3da..956b8b5f9 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 @@ -29,16 +27,15 @@ The CLI also has utilities for maintaining your documentation, including command - 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) - 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 @@ -46,14 +43,12 @@ The CLI also has utilities for maintaining your documentation, including command ``` - **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**. @@ -91,21 +86,17 @@ 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 -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 @@ -113,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 @@ -123,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 @@ -145,21 +134,21 @@ The CLI tool prompts you for a project name and [theme](/customize/themes) to fi | `--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 -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 @@ -175,17 +164,17 @@ If this `mint update` command is not available on your local version, re-install ### 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 @@ -203,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 @@ -216,17 +205,17 @@ 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 -Rename and update all references to files with the following command: +Rename and update all references: ```bash mint rename @@ -234,68 +223,46 @@ 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 -While developing locally, we recommend using extensions in your IDE to recognize and format MDX files. - -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. +Use IDE extensions for MDX: -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 - 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. - - If you don't use npm or don't see it in the -g list, try `which mint` to locate the installation. + If both `mint` and `mintlify` are installed, uninstall `mintlify`: - If you have a package named `mint` and a package named `mintlify` installed, you should 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`. diff --git a/quickstart.mdx b/quickstart.mdx index bc56bad0b..e5924bd80 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -4,33 +4,23 @@ 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 -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. - 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. ## 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/). - 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