diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx index 85504e746..c00447f69 100644 --- a/api-playground/troubleshooting.mdx +++ b/api-playground/troubleshooting.mdx @@ -4,17 +4,16 @@ description: "Common issues with API References" icon: "triangle-exclamation" --- -API pages are complicated. As a result, there are a lot of things that can go wrong. -Here's a list of common issues we've seen customers run into: +API pages can be complex, and several common issues may arise. Here's a list of problems we frequently see and how to resolve them: - In this scenario, it's likely that either Mintlify cannot find your OpenAPI document, + When all OpenAPI pages are blank, this typically means either Mintlify cannot find your OpenAPI document, or your OpenAPI document is invalid. - Running `mintlify dev` locally should reveal some of these issues. + Running `mintlify dev` locally will reveal most of these issues. - To verify your OpenAPI document will pass validation: + To verify your OpenAPI document's validity: 1. Visit [this validator](https://apitools.dev/swagger-parser/online/) 2. Switch to the "Validate text" tab @@ -22,11 +21,12 @@ Here's a list of common issues we've seen customers run into: 4. Click "Validate it!" If the text box that appears below has a green border, your document has passed validation. - This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document - passes validation here, there's a great chance the problem is elsewhere. + This is the same validation package Mintlify uses to validate OpenAPI documents, so if your document + passes validation here, the issue likely lies elsewhere. Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification, - you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3): + you will encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) + by selecting Edit > Convert to OpenAPI 3: @@ -35,10 +35,10 @@ Here's a list of common issues we've seen customers run into: - This is usually caused by a misspelled `openapi` field in the page metadata. Make sure - the HTTP method and path match the HTTP method and path in the OpenAPI document exactly. + This issue usually stems from a mismatched `openapi` field in the page metadata. Ensure + the HTTP method and path exactly match those in your OpenAPI document. - Here's an example of how things might go wrong: + Here's an example of a common mismatch: ```md get-user.mdx --- @@ -52,12 +52,12 @@ paths: get: ... ``` - Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI + Notice that the path in the `openapi` field has a trailing slash, while the path in the OpenAPI document does not. - Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document - in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI - documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this: + Another common issue is referencing the wrong OpenAPI file. When specifying a particular OpenAPI document + in the `openapi` field, verify the filename is correct. For example, if you have two OpenAPI + documents `openapi/v1.json` and `openapi/v2.json`, your metadata should look like this: ```md api-reference/v1/users/get-user.mdx --- @@ -68,17 +68,16 @@ openapi: "v1 GET /users/{id}" - If you have a custom domain configured, this could be an issue with your reverse proxy. By - default, requests made via the API Playground start with a `POST` request to the - `/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET` - requests, then all of these requests will fail. To fix this, configure your reverse proxy to - allow `POST` requests to the `/api/request` path. - - Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure - Mintlify to send requests directly to your backend with the `api.playground.disableProxy` - setting in the `mint.json`, as described [here](/settings/global#api-configurations). This will - likely require you to configure CORS on your server, as these requests will now come directly - from your users' browsers. + For sites with a custom domain, this may be caused by your reverse proxy configuration. By + default, the API Playground makes `POST` requests to the `/api/request` path on your docs site. + If your reverse proxy only allows `GET` requests, these API Playground requests will fail. + To resolve this, configure your reverse proxy to allow `POST` requests to the `/api/request` path. + + If you cannot configure your reverse proxy to accept `POST` requests, you can set Mintlify + to send requests directly to your backend using the `api.playground.disableProxy` + setting in your `mint.json`, as described in the [API Configurations documentation](/settings/global#api-configurations). + Note that this approach requires CORS configuration on your server since requests will come directly + from users' browsers. - + \ No newline at end of file diff --git a/mint.json b/mint.json index 65c9d33d9..f1e76d954 100644 --- a/mint.json +++ b/mint.json @@ -65,12 +65,14 @@ "icon": "pen-paintbrush", "pages": [ "development", + "web-editor", "web-editor" ] }, "settings/global", "settings/navigation", - "migration" + "migration", + "quickstart" ] }, { @@ -105,6 +107,7 @@ "api-playground/mdx/authentication" ] }, + "api-playground/troubleshooting", "api-playground/troubleshooting" ] }, @@ -164,9 +167,12 @@ "settings/authentication-personalization/personalization-setup/choosing-a-handshake", "settings/authentication-personalization/personalization-setup/shared-session", "settings/authentication-personalization/personalization-setup/jwt", + "settings/authentication-personalization/personalization-setup/oauth", "settings/authentication-personalization/personalization-setup/oauth" ] }, + "settings/authentication-personalization/sending-data", + "settings/authentication-personalization/authentication", "settings/authentication-personalization/sending-data" ] }, diff --git a/quickstart.mdx b/quickstart.mdx index fd4ba0858..288c92096 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -17,20 +17,20 @@ icon: "rocket" ## Getting Started -Welcome! Follow the instructions below to learn how to deploy, update and +Welcome! Follow the instructions below to learn how to deploy, update, and supercharge your documentation with Mintlify. ### Creating the Repository Mintlify docs are rendered from MDX files and configurations defined in our [starter kit](https://github.com/mintlify/starter). We use GitHub to integrate -your docs with your code, and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started. +your docs with your code and make source control effortless. Onboard through the [dashboard](https://dashboard.mintlify.com) or clone our [starter kit](https://github.com/mintlify/starter) to get started. - + - Install our GitHub app to ensure that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository. + Install our GitHub App to ensure that your updates are automatically deployed when you push changes. You can find the installation link in the [dashboard](https://dashboard.mintlify.com/settings), on the Settings page. Upon successful installation, a check mark will appear next to the commit hash of the repository. ![GitHub Bot Verification](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/github-bot-verification.png) @@ -40,9 +40,9 @@ your docs with your code, and make source control effortless. Onboard through th If you want your docs to live alongside your code as a monorepo setup, you - can: 1. Move your docs content to your monorepo. 2. Specify the path to your - `mint.json` in the - [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings) + can: + 1. Move your docs content to your monorepo + 2. Specify the path to your `mint.json` in the [dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings) Monorepo setup - 1. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). - 2. Once git is installed, clone your docs repository using `git clone `. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). + 1. Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). + 2. Once Git is installed, clone your docs repository using `git clone `. If you haven't set it up yet, now would be a good time to do so with these [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). 3. Use your favorite IDE to open the repository. 4. Install our Mintlify CLI to preview changes with `npm i -g mintlify`. @@ -76,15 +76,15 @@ your docs. - + - Learn more about how to use the web editor on our [guide](/web-editor). + Learn more about how to use the Web Editor on our [guide](/web-editor). - Easily customize colors, logos and buttons among other configurations in our `mint.json` file. Start with these basic configurations: + Easily customize colors, logos, and buttons among other configurations in our `mint.json` file. Start with these basic configurations: ```json "name": "Your Company" @@ -123,11 +123,10 @@ your docs. - Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub app is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com). + Once ready, commit and push your changes to update your docs site. Here is a [guide](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) on how to do that. If the GitHub App is unable to successfully deploy your changes, you can manually update your docs through our [dashboard](https://dashboard.mintlify.com). - ![Manual - Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) + ![Manual Update](https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/manual-update.png) @@ -142,13 +141,13 @@ your docs. "openapi": "link-to-your-openapi-file" ``` - 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files as: + 2. Use our [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) to autogenerate your OpenAPI endpoints files: ```bash npx @mintlify/scraping@latest openapi-file ``` - 3. Finally, include the generated endpoint MDX files to your `mint.json` under `navigation`. + 3. Finally, include the generated endpoint MDX files in your `mint.json` under `navigation`. For a complete guide on using Mintlify with OpenAPI, check out [this guide](/api-playground/openapi/setup). [This guide](/api-playground/openapi/writing-openapi) explains how to configure your API authentication methods. For manual API references definition, explore [our syntax](/api-playground/overview). @@ -156,7 +155,7 @@ your docs. - Our in-house analytics give you insights into page views, search analytics, session recordings and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics). + Our in-house analytics give you insights into page views, search analytics, session recordings, and more. Access these on your [dashboard](https://dashboard.mintlify.com/analytics). We also support integrations with a range of analytics providers. You can find the list of providers [here](/integrations/analytics/overview). @@ -180,7 +179,7 @@ Navigate to your [dashboard settings](https://www.dashboard.mintlify.com/setting -Congrats! You've set up your Mintlify Docs and it's looking amazing! Need +Congrats! You've set up your Mintlify Docs and they're looking amazing! Need support or want to give some feedback? You can join our [community](https://mintlify.com/community) or drop us an email at -[support@mintlify.com](mailto:support@mintlify.com). +[support@mintlify.com](mailto:support@mintlify.com). \ No newline at end of file diff --git a/settings/authentication-personalization/authentication.mdx b/settings/authentication-personalization/authentication.mdx index 81c5b8a7e..bbdae4666 100644 --- a/settings/authentication-personalization/authentication.mdx +++ b/settings/authentication-personalization/authentication.mdx @@ -3,23 +3,20 @@ title: "Authentication" description: "Guarantee privacy of your docs by authenticating users" --- -Authentication offers full privacy for all of your -documentation content by requiring users to authenticate before viewing any content, such as: +Authentication offers full privacy for all of your documentation content by requiring users to authenticate before viewing any content, including: - Documentation page content -- Images used in documentation pages +- Images used in documentation pages - Search results - AI chat interactions -You can authenticate users through handshake methods such as: +You can authenticate users through the following handshake methods: - [Password](./authentication-setup/password) -- [JWT](./authentication-setup/jwt) -- [OAuth](./authentication-setup/oauth) -- [Mintlify dashboard](./authentication-setup/mintlify) +- [JWT](./authentication-setup/jwt) +- [OAuth 2.0](./authentication-setup/oauth) +- [Mintlify Dashboard](./authentication-setup/mintlify) -Authentication is similar to our [Personalization](./personalization) offering, but with guaranteed privacy. In addition -to securing your documentation content, all features that are available via -Personalization are also available via Authentication. +Authentication is similar to our [Personalization](./personalization) offering but with guaranteed privacy. In addition to securing your documentation content, all features available via Personalization are also available via Authentication. -Check out our docs for more info on [choosing Authentication vs Personalization](./authentication-vs-personalization). +To learn more about choosing between Authentication and Personalization, read our guide on [Authentication vs. Personalization](./authentication-vs-personalization). \ No newline at end of file diff --git a/settings/authentication-personalization/personalization-setup/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx index d786a042f..781eec62a 100644 --- a/settings/authentication-personalization/personalization-setup/oauth.mdx +++ b/settings/authentication-personalization/personalization-setup/oauth.mdx @@ -4,42 +4,42 @@ description: 'Integrate with your OAuth server to enable user login via the PKCE --- - This is the documentation for the OAuth **Personalization** Handshake. The steps for setting up the [OAuth **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/oauth) are slightly different. + This is the documentation for the OAuth 2.0 **Personalization** Handshake. The steps for setting up the [OAuth 2.0 **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/oauth) are slightly different. -If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience. +If you have an existing OAuth 2.0 server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience. ## Implementation - Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [User](../sending-data) format. Take note of the scope or scopes required to access this endpoint. + Create an API endpoint that can be accessed with an OAuth 2.0 access token, and create a response with a JSON payload following the [User](../sending-data) format. Take note of the scope or scopes required to access this endpoint. - Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields: + Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth 2.0 option, and fill out the required fields: - - **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters. + - **Authorization URL**: The base URL for the authorization request. We will add the appropriate query parameters to this URL. - **Client ID**: An ID for the OAuth 2.0 client to be used. - **Scopes**: An array of scopes that will be requested. - **Token URL**: The base URL for the token exchange request. - - **Info API URL**: The endpoint that will be hit to retrieve user info. + - **Info API URL**: The endpoint that will be used to retrieve user info. - - Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server. + + Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth 2.0 server. ## Example -I have an existing OAuth server that supports the PKCE flow. I want to set up authentication for my docs hosted at `foo.com/docs`. +I have an existing OAuth 2.0 server that supports the PKCE flow. I want to set up authentication for my docs hosted at `foo.com/docs`. -To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user's custom data according to Mintlify’s specification. +To set up authentication with Mintlify, I first create an endpoint at `api.foo.com/docs/user-info`. This endpoint requires an OAuth 2.0 access token with the `docs-user-info` scope and responds with the user's custom data according to Mintlify's specification. -I then go to the Mintlify dashboard settings, navigate to the Personalization settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint: +Next, I navigate to the Mintlify dashboard settings, go to the Personalization settings, select OAuth 2.0, and enter the relevant values for the OAuth 2.0 flow and Info API endpoint: - **Authorization URL**: `https://auth.foo.com/authorization` - **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` - **Scopes**: `['docs-user-info']` - **Token URL**: `https://auth.foo.com/exchange` - **Info API URL**: `https://api.foo.com/docs/user-info` -Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings. +Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth 2.0 client configuration settings. \ No newline at end of file diff --git a/settings/authentication-personalization/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx index e969fa8bc..244c6871e 100644 --- a/settings/authentication-personalization/sending-data.mdx +++ b/settings/authentication-personalization/sending-data.mdx @@ -24,27 +24,25 @@ type User = { type="number" > The time at which this information should expire, in **seconds since epoch**. If the user loads the page and the current time is after this value, the stored data will be deleted. - For JWT Handshakes: This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks. + For JWT Handshakes: The `expiresAt` field is *not* the same as the `exp` claim in the JWT. The `exp` claim determines when a JWT should no longer be considered valid and should be set as low as possible (10 seconds or lower in this case). The `expiresAt` field determines when retrieved data should be considered stale and can be configured from one day to several weeks. - A list of groups that the user belongs to. This will determine which pages should be shown to this user. If any of these groups is listed in the `groups` field of a page’s metadata, that page will be shown. + A list of groups that the user belongs to. This will determine which pages should be shown to this user. If any of these groups is listed in the `groups` field of a page's metadata, that page will be shown. - A bag of values that can be accessed from within MDX content using the `user` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {user.firstName}!` + A collection of values that can be accessed from within MDX content using the `user` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {user.firstName}!` - User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send `{ server: { subdomain: 'foo' } }` as my `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value. + User-specific values that will be prefilled in the API Playground if supplied. For example, if each of your customers makes requests at a specific subdomain, you can send `{ server: { subdomain: 'foo' } }` as your `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value. - The`header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To know if a field will be prefilled, navigate to your existing docs and check if the field is in either the `Authorization` or `Server` section. - - - \ No newline at end of file + The `header`, `query`, and `cookie` fields will only be prefilled if they are part of your [security scheme](https://swagger.io/docs/specification/authentication/). Creating a standard header parameter named `Authorization` is not sufficient to enable this feature. To verify if a field will be prefilled, navigate to your existing docs and check if the field appears in either the `Authorization` or `Server` section. + \ No newline at end of file diff --git a/web-editor.mdx b/web-editor.mdx index 0c945d94b..85f07f1b8 100644 --- a/web-editor.mdx +++ b/web-editor.mdx @@ -5,56 +5,56 @@ description: 'Edit your docs directly from the dashboard with live previews.' Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`. -The editor includes a few key features to integrate directly into your existing git workflow, -like creating branches, pull requests, commits, and diffs for your current changes. +The editor includes features that integrate directly into your existing Git workflow, +such as creating branches, pull requests, commits, and diffs for your current changes. It also includes a fully editable experience for changing and adding content directly, even with custom components. -If you understand git workflows and our integrations already, you can skip to [here](#editing-content). +If you understand Git workflows and our integrations already, you can skip to [here](#editing-content). ## Git and update workflows ### Git basics While Web Editor means you don't need to go to GitHub or your command line to make -changes, it's still helpful to know the basics of git. +changes, it's still helpful to know the basics of Git. Git terminology: -- **Repository**: The folder in which your code lives. It can be local (on your computer) or remote (like GitHub). +- **Repository**: The folder where your code lives. It can be local (on your computer) or remote (like GitHub). - **Commit**: A snapshot of changes made to files in the repository. - **Branch**: A separate line of development. It's a working copy of the code that allows you to work on changes without affecting the main version. -- **Pull request:** A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live. +- **Pull Request**: A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live. ### Making updates -In order to make updates to your docs, we include a few buttons specifically to -integrate with your git workflow. +To make updates to your docs, we include buttons that integrate +with your Git workflow. - If you haven't done so already, please install the Mintlify GitHub app to your GitHub account. + If you haven't done so already, please install the Mintlify GitHub App to your GitHub account. You can find [documentation here](#1-deploying-your-docs-repository), or you can install the app in the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app) - page of the dashboard. + of the dashboard. - In order to make changes to your docs, you might want to change from the main branch + To make changes to your docs, you might want to change from the main branch to avoid publishing directly to your main docs site. - To do this, you can open the branches modal on the top left of the editor. + You can open the branches modal on the top left of the editor. - From here, you can either switch to a different git branch than `main`, or you can + From here, you can either switch to a different Git branch than `main`, or you can create a new branch by clicking the **"New Branch"** button. @@ -65,22 +65,22 @@ integrate with your git workflow. After you create a new branch, you'll automatically be switched, and all changes you make will be made to this new branch until you change branches again or reload the page. - By default, when you load the page again, you'll default to the main branch. + By default, when you load the page again, you'll return to the main branch. - As a best practice, you should always create a new branch to make changes so you can submit a pull request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we'll try to open a pull request for you. + As a best practice, you should always create a new branch to make changes so you can submit a Pull Request for review by other teammates. You also may not have permissions to make changes to the main branch, in which case we'll try to open a Pull Request for you. - In order to make a commit, you have two options, both of which appear on the top + To make a commit, you have two options, both of which appear on the top right of the editor: If you're on the main branch of your docs repository, you can push a commit directly to the repo by clicking the **"Publish"** button. You'll see your changes - reflect in your git branch the next time you run `git pull`. + reflected in your Git branch the next time you run `git pull`. @@ -90,7 +90,7 @@ integrate with your git workflow. If you're not on the main branch, you can push a commit to your branch by clicking - on the **"Save Changes"** button. If you're ready to publish a pull request to put your branch + on the **"Save Changes"** button. If you're ready to publish a Pull Request to put your branch up for review, you can click the **"Publish Pull Request"** button. @@ -100,13 +100,13 @@ integrate with your git workflow. - This will create the pull request for you on GitHub using the branch you selected onto + This will create the Pull Request for you on GitHub using the branch you selected onto your main branch. - - If you do put your pull request up for review, you can edit the title and description - of the PR, but a default Mintlify title will be provided for you if you leave it + + If you put your Pull Request up for review, you can edit the title and description + of the PR, but a default Mintlify title will be provided if you leave it empty. @@ -128,7 +128,7 @@ commands you have access to after typing `/` in the **"Visual Editor"** mode: -As you type, you'll see more options pop up: +As you type, you'll see more options appear: @@ -172,24 +172,24 @@ Here are the types of content blocks available to add in the **"Visual Editor"** ### Adding images You can add images to your page by typing `/image` and either clicking on the **"Image"** -option or hitting ↓ + Enter on the **"Image"** option. +option or pressing ↓ + Enter on the **"Image"** option. -This will open up the image modal where you have the option to either upload a new -image or use an existing image from the repo. +This will open the image modal where you have the option to either upload a new +image or use an existing image from the repository. -Uploading an image can be done through the modal: +You can upload an image through the modal: -And you can preview an existing image before you add it. +And you can preview an existing image before adding it. @@ -198,7 +198,7 @@ And you can preview an existing image before you add it. ### Editing images -In order to edit images, you just have to hover over the image to see the **"Delete"** +To edit images, hover over the image to see the **"Delete"** and **"Edit"** buttons on the top right of the image. @@ -206,20 +206,20 @@ and **"Edit"** buttons on the top right of the image. -Clicking the **"Edit"** button lets you edit the attributes of the image. +Clicking the **"Edit"** button lets you edit the image's attributes. -If you want to update the source of an image to be a new image that you haven't yet -uploaded, you have to first delete the image you're changing, and then add a new one +To update an image's source to a new image that you haven't yet +uploaded, first delete the existing image, then add a new one using the [instructions above](#adding-images). ## Editor modes -In order to offer the most flexibility, the editor has three modes: +To offer the most flexibility, the editor has three modes: @@ -228,47 +228,47 @@ In order to offer the most flexibility, the editor has three modes: ### Visual Editor -The **"Visual Editor"** is the typical WYSIWYG mode you'd see in something like Notion. -It offers you a view into your docs in a fully editable way that reflects what the final -page would look like on your main docs site. +The **"Visual Editor"** is the typical WYSIWYG mode you'd see in tools like Notion. +It offers a view of your docs in a fully editable format that reflects what the final +page will look like on your main docs site. ### Source Editor -The **"Source Editor"** offers you a way to edit your MDX files in code, the same way -you'd do in your IDE. This offers less flexibility, in that our components aren't available -for auto-complete, but it does have two unique advantages. +The **"Source Editor"** lets you edit your MDX files in code, similar to using +your IDE. While it offers less flexibility since our components aren't available +for auto-complete, it has two unique advantages: -1. It allows you to edit props of components (see our [limitations below](#current-limitations)) -which is currently not available in **"Visual Editor"** mode yet. +1. It allows you to edit component props (see our [limitations below](#current-limitations)) +which is currently not available in **"Visual Editor"** mode. -2. It allows you to correct syntax errors which might've appeared in your repo that -might not be compatible with **"Visual Editor"** mode until you've fixed them. +2. It allows you to correct syntax errors that might appear in your repository that +aren't compatible with **"Visual Editor"** mode until fixed. ### Diff View -The **"Diff View"** is a way to view the changes made to a specific document before +The **"Diff View"** shows the changes made to a specific document before committing it to your repository. -This will help you see changes you've made along with formatting changes made by +This helps you see both content changes and formatting changes made by the editor. ## Current limitations -We do have a few current limitations in the editor that we're working to resolve. +We have a few current limitations in the editor that we're working to resolve. You currently cannot live-update your navigation based on added/edited files. You - still have to manually edit renamed, added, and deleted files in your `mint.json` + still need to manually edit renamed, added, and deleted files in your `mint.json` - We currently don't show any previews for custom snippets. This is on our roadmap to support + We currently don't show previews for custom snippets. This is on our roadmap to support as fully editable components. - We currently don't show any previews for OpenAPI specs. This is on our roadmap to support + We currently don't show previews for OpenAPI specifications. This is on our roadmap to support as a read-only preview.