diff --git a/mint.json b/mint.json
index 51a98d110..8a0dacc0a 100644
--- a/mint.json
+++ b/mint.json
@@ -63,11 +63,17 @@
{
"group": "Editing",
"icon": "pen-paintbrush",
- "pages": ["development", "web-editor"]
+ "pages": [
+ "development",
+ "web-editor"
+ ]
},
"settings/global",
"settings/navigation",
- "migration"
+ "migration",
+ "web-editor",
+ "settings/github",
+ "settings/versioning"
]
},
{
@@ -124,7 +130,10 @@
{
"icon": "code",
"group": "Custom Scripts",
- "pages": ["advanced/custom/css", "advanced/custom/js"]
+ "pages": [
+ "advanced/custom/css",
+ "advanced/custom/js"
+ ]
},
{
"icon": "folder",
@@ -150,7 +159,8 @@
"settings/authentication-personalization/authentication-setup/password",
"settings/authentication-personalization/authentication-setup/jwt",
"settings/authentication-personalization/authentication-setup/oauth",
- "settings/authentication-personalization/authentication-setup/mintlify"
+ "settings/authentication-personalization/authentication-setup/mintlify",
+ "settings/authentication-personalization/authentication-setup/jwt"
]
},
{
@@ -159,16 +169,20 @@
"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/personalization-setup/jwt"
]
},
- "settings/authentication-personalization/sending-data"
+ "settings/authentication-personalization/sending-data",
+ "settings/authentication-personalization/personalization"
]
},
{
"icon": "plug",
"group": "Extensions",
- "pages": ["advanced/widget/chat"]
+ "pages": [
+ "advanced/widget/chat"
+ ]
},
{
"icon": "brackets-curly",
@@ -214,7 +228,10 @@
},
{
"group": "SDKs",
- "pages": ["integrations/sdks/speakeasy", "integrations/sdks/stainless"]
+ "pages": [
+ "integrations/sdks/speakeasy",
+ "integrations/sdks/stainless"
+ ]
},
{
"group": "Support",
@@ -226,7 +243,10 @@
},
{
"group": "Privacy",
- "pages": ["integrations/privacy/overview", "integrations/privacy/osano"]
+ "pages": [
+ "integrations/privacy/overview",
+ "integrations/privacy/osano"
+ ]
},
{
"group": "Components",
@@ -258,7 +278,9 @@
},
{
"group": "Changelog",
- "pages": ["changelog/overview"]
+ "pages": [
+ "changelog/overview"
+ ]
}
],
"footer": {
@@ -342,4 +364,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
-}
+}
\ No newline at end of file
diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx
index d35fd7e3a..ee9403202 100644
--- a/settings/authentication-personalization/authentication-setup/jwt.mdx
+++ b/settings/authentication-personalization/authentication-setup/jwt.mdx
@@ -4,45 +4,45 @@ description: 'Use a customized login flow to authenticate users'
---
- This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different.
+ This is the documentation for the JSON Web Token (JWT) **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different.
-If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.
+If you don't have a dashboard or want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.
## Implementation
- Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
+ Navigate to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key in a secure location where your backend can access it.
- Create a login flow that does the following:
- - Authenticate the user
- - Create a JWT containing the authenticated user's info in the [User](../sending-data) format
- - Sign the JWT with the secret key, using the EdDSA algorithm
- - Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash
+ Create a login flow that performs the following steps:
+ - Authenticates the user
+ - Creates a JWT containing the authenticated user's info in the [User](../sending-data) format
+ - Signs the JWT with the secret key using the EdDSA algorithm
+ - Creates a redirect URL to the `/login/jwt-callback` path of your docs, including the JWT as the hash
- Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings.
+ Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and provide the login URL in your Authentication settings.
## Example
-I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
-to be completely separate from my dashboard (or I don’t have a dashboard at all).
+Let's say you want to set up authentication for your docs hosted at `docs.foo.com`. You want your docs to be completely separate from your dashboard (or you don't have a dashboard).
-To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
-JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
-for my users. At the end of this login flow, once I have verified the identity of the user,
-I create a JWT containing the user’s custom data according to Mintlify’s specification.
-I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
-form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user.
+To set up authentication with Mintlify:
-I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the
-Login URL field.
+1. Generate a JWT secret from your Mintlify dashboard
+2. Create a web URL at `https://foo.com/docs-login` that initiates a login flow for your users
+3. At the end of this login flow, after verifying the user's identity:
+ - Create a JWT containing the user's custom data according to Mintlify's specification
+ - Use a JWT library to sign the JWT with your Mintlify secret
+ - Create a redirect URL in the format `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`
+ - Redirect the user to this URL
+4. Configure the Mintlify dashboard settings by entering `https://foo.com/docs-login` as the Login URL
-Here's what the code might look like:
+Here's example code showing how to implement this:
```ts TypeScript
@@ -86,7 +86,7 @@ async def return_mintlify_auth_status(current_user):
jwt_token = jwt.encode(
payload={
'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
- 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
+ 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 2 week session expiration
'groups': ['admin'] if current_user.is_admin else [],
'content': {
'firstName': current_user.first_name,
@@ -99,4 +99,4 @@ async def return_mintlify_auth_status(current_user):
return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
```
-
+
\ No newline at end of file
diff --git a/settings/authentication-personalization/personalization-setup/jwt.mdx b/settings/authentication-personalization/personalization-setup/jwt.mdx
index 3e4fe195a..a2400e6b1 100644
--- a/settings/authentication-personalization/personalization-setup/jwt.mdx
+++ b/settings/authentication-personalization/personalization-setup/jwt.mdx
@@ -7,21 +7,20 @@ description: 'Use a customized login flow to authenticate users'
This is the documentation for the JWT **Personalization** Handshake. The steps for setting up the [JWT **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/jwt) are slightly different.
-
-If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to send user info to your docs via a JWT in the URL.
+If you don't have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to send user information to your docs via a JWT (JSON Web Token) in the URL.
## Implementation
- Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
+ Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key in a secure location where it can be accessed by your backend.
- Create a login flow that does the following:
- - Authenticate the user
- - Create a JWT containing the authenticated user's info in the [User](../sending-data) format
- - Sign the JWT with the secret key, using the EdDSA algorithm
- - Create a redirect URL back to your docs, including the JWT as the hash
+ Create a login flow that performs the following actions:
+ - Authenticates the user
+ - Creates a JWT containing the authenticated user's information in the [User](../sending-data) format
+ - Signs the JWT with the secret key using the EdDSA algorithm
+ - Creates a redirect URL back to your docs that includes the JWT as the hash parameter
Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Personalization settings.
@@ -30,20 +29,18 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs
## Example
-I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
-to be completely separate from my dashboard (or I don’t have a dashboard at all).
+In this example, we'll set up authentication for docs hosted at `docs.foo.com`. We want the docs to be completely separate from the dashboard (or we don't have a dashboard at all).
-To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
-JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
-for my users. At the end of this login flow, once I have verified the identity of the user,
-I create a JWT containing the user’s custom data according to Mintlify’s specification.
-I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
-form `https://docs.foo.com#{SIGNED_JWT}`, and redirect the user.
+To set up authentication with Mintlify:
-I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the
-Login URL field.
+1. First, generate a JWT secret from the Mintlify dashboard
+2. Create a web URL at `https://foo.com/docs-login` that initiates a login flow for your users
+3. After verifying the user's identity at the end of the login flow, create a JWT containing the user's custom data according to Mintlify's specification
+4. Use a JWT library to sign the JWT with your Mintlify secret
+5. Create a redirect URL in the format `https://docs.foo.com#{SIGNED_JWT}`
+6. Configure the login URL (`https://foo.com/docs-login`) in the Mintlify dashboard settings
-Here's what the code might look like:
+Here's an example implementation:
```ts
import * as jose from 'jose';
@@ -70,14 +67,12 @@ export async function handleRequest(req: Request, res: Response) {
return res.redirect(`https://docs.foo.com#${jwt}`);
}
-
```
## Preserving Anchors
-Post-login, if you'd like to redirect to a specific anchor on the page, you can use the following format to create the redirect URL: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`.
-
-Example:
+After login, you can preserve specific anchor locations on the page by using a special URL format that includes both the JWT and the anchor parameter: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`.
-- Original: `https://docs.foo.com/quickstart#step-one`
-- Redirect: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one`
+Examples:
+- Original URL: `https://docs.foo.com/quickstart#step-one`
+- Redirect URL with JWT: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one`
\ No newline at end of file
diff --git a/settings/authentication-personalization/personalization.mdx b/settings/authentication-personalization/personalization.mdx
index 05baef8e8..bf2ab8ebe 100644
--- a/settings/authentication-personalization/personalization.mdx
+++ b/settings/authentication-personalization/personalization.mdx
@@ -4,20 +4,20 @@ description: "A list of features unlocked with Personalization"
---
Personalization refers to a suite of features that allow you to customize your
-documentation experience based on some information about the user. There are
+documentation experience based on information about the user. There are
three major features of Personalization:
-- **Customize MDX content** with a user's information, such as their name, plan, or title.
+- **Customize MDX Content** with user information such as name, plan, or title.
-- **Prefill API keys** in the API Playground for streamlined use.
+- **Prefill API Keys** in the API Playground for streamlined usage.
-- **Selectively show pages** in the navigation based on a user's groups.
+- **Selectively Show Pages** in the navigation based on user groups.
## How to Use
### Customizing MDX Content
-When writing content, you can use the `user` variable to access the information you have sent to your docs. Here's a simple example:
+When writing content, you can use the `user` variable to access any information you have sent to your docs. Here's a simple example:
Hello, {user.name ?? 'reader'}!
@@ -25,7 +25,7 @@ Hello, {user.name ?? 'reader'}!
Hello, {user.name ?? 'reader'}!
```
-This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the Personalization feature based on the customer's existing plan:
+This feature becomes even more powerful when paired with custom data about the user. Here's a real-world example that provides specific instructions about accessing the Personalization feature based on the customer's existing plan:
Personalization is an enterprise feature. {
user.org === undefined
@@ -46,21 +46,21 @@ Personalization is an enterprise feature. {
```
- The information in `user` is only available after a user has logged in. For
- logged out users, the value of `user` will be `{}`. To prevent the page from
+ The information in the `user` object is only available after a user has logged in. For
+ logged-out users, the value of `user` will be `{}`. To prevent your page from
crashing for logged-out users, always use optional chaining on your `user`
- fields, e.g. `{user.org?.plan}`
+ fields (e.g., `{user.org?.plan}`).
### Prefilling API Keys
-If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground.
+When you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Ensure that the field name in the user info exactly matches the name in the API Playground.
### Showing/Hiding Pages
-By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata.
-When determining which pages to show to the user, Mintlify will check which groups the user belongs to.
-If the user is not in any of the groups listed in the page metadata, the page will not be shown.
+By default, every page is visible to every user. To restrict which pages are visible to your users, add a `groups` field in your page metadata.
+When determining which pages to show to the user, Mintlify checks which groups the user belongs to.
+If the user is not in any of the groups listed in the page metadata, that page will not be shown.
```md
---
@@ -70,7 +70,7 @@ groups: ["admin"]
---
```
-Here's a table that displays whether a page is shown for different combinations of `groups` in User and page metadata:
+This table shows whether a page is visible based on different combinations of `groups` in User and page metadata:
| | `groups` not in User | `groups: []` in User | `groups: ['admin']` in User |
| :------------------------------ | :------------------: | :------------------: | :-------------------------: |
@@ -79,6 +79,5 @@ Here's a table that displays whether a page is shown for different combinations
| `groups: ['admin']` in metadata | ❌ | ❌ | ✅ |
- Note that an empty array in the page metadata is interpreted as "No groups
- should see this page."
-
+ An empty array in the page metadata is interpreted as "No groups should see this page."
+
\ No newline at end of file
diff --git a/settings/github.mdx b/settings/github.mdx
index 310499c06..3e9947e41 100644
--- a/settings/github.mdx
+++ b/settings/github.mdx
@@ -5,22 +5,21 @@ icon: 'github'
---
Mintlify integrates with the GitHub API, enabling synchronization between your
-docs and your GitHub repository. This integration is made possible through the
-utilization of
+documentation and your GitHub repository. This integration is made possible through
[GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps).
## Installation
-To begin, you need to install the Mintlify GitHub App into the GitHub account
-where your docs repo resides. Installing a GitHub App requires either
-organization ownership or admin permissions in a repository. If you lack the
-necessary permissions, the repository owner will need to approve the request.
-You can access the installation page by logging into the
+To begin, you need to install the Mintlify GitHub App in the GitHub account where
+your documentation repository resides. Installing a GitHub App requires either
+organization ownership or admin permissions for the repository. If you lack the
+necessary permissions, the repository owner will need to approve the installation
+request. You can access the installation page by logging into the
[Mintlify dashboard](https://dashboard.mintlify.com).
-For GitHub Apps, you can choose to only give permissions to a single repository.
-We highly recommend you do so as we only need access to the repository where
-your docs are hosted.
+When installing a GitHub App, you can choose to grant permissions to a single repository.
+We highly recommend this approach since we only need access to the repository where
+your documentation is hosted.
@@ -28,35 +27,33 @@ your docs are hosted.
## Permissions
-During the installation of our GitHub app, you will be prompted to grant certain
-permissions:
+During the installation of our GitHub App, you will be prompted to grant these
+specific permissions:
- Read and write access to `checks`, `contents`, `deployments`, `pull requests`,
and `workflows`
-These permissions are leveraged to provide a seamless experience when managing
-your docs.
+These permissions enable a seamless experience when managing your documentation:
-When you make a commit to the branch you configured as your docs deployment
-branch, we fetch the contents of the files changed to update your docs. To
-accomplish this we need read access to your `contents`.
+- When you make a commit to your configured documentation deployment branch, we fetch
+ the contents of the changed files to update your docs. This requires read access
+ to your repository's `contents`.
-When pull requests are created we create a check and preview deployment which is
-why we need write access to `checks` and `deployments`.
+- When pull requests are created, we create a check and preview deployment. This
+ requires write access to `checks` and `deployments`.
-Inside the Mintlify web editor, Mintlify works on your behalf to create branches
-and pull requests which is why we need write access to `pull requests` and
-`workflows`.
+- Within the Mintlify web editor, we create branches and pull requests on your
+ behalf. This requires write access to `pull requests` and `workflows`.
- If you are concerned about the write permissions, the GitHub App will only
- have access to the repos you give it access to _and_ if you have branch
- protections on it _cannot_ push directly to your branches - it abides by your
- branch protection rules.
+ If you are concerned about the write permissions, note that the GitHub App will
+ only have access to repositories you explicitly grant it access to. Additionally,
+ if you have branch protection rules in place, the GitHub App cannot bypass them
+ - it must follow your branch protection settings.
-## Repositories Installations
+## Repository Access
-When installing our GitHub app, you will be prompted to select all repositories
-or a subset of them. This selection can be changed at any time by going to the
-[GitHub app settings](https://github.com/apps/mintlify/installations/new).
+When installing our GitHub App, you will be prompted to select either all repositories
+or a specific subset. You can modify this selection at any time through the
+[GitHub App settings](https://github.com/apps/mintlify/installations/new).
\ No newline at end of file
diff --git a/settings/versioning.mdx b/settings/versioning.mdx
index bc60a79b1..85bf1f0f7 100644
--- a/settings/versioning.mdx
+++ b/settings/versioning.mdx
@@ -4,17 +4,17 @@ description: "Build separate versions or localizations"
icon: "square-chevron-down"
---
-Mintlify supports versioning or localization. You can use one or the other, not both.
+Mintlify supports either versioning or localization. Note that you can use one or the other, but not both simultaneously.
-These guides will assume `v1` pages are in a folder named `v1`, `v2` pages are in a folder named `v2`, and so on. While this method of structuring your files isn't strictly necessary, it's a great way to keep your files organized.
+These guides assume that your content for different versions is organized in folders named `v1`, `v2`, and so on. While this file structure isn't strictly necessary, it's recommended for keeping your content well-organized.
## Versioning
### Setup
-Add `"versions": ["v2", "v1"]` to your `mint.json` file where `v1` and `v2` are the names of your versions. You can put any number of versions in this array. The first version from the array serves as the default version.
+Add `"versions": ["v2", "v1"]` to your `mint.json` file, where `v1` and `v2` are your version names. You can include any number of versions in this array. The first version listed will serve as the default version.
-If you would like to specify a default version, you can do so like this:
+To explicitly specify a default version, use this format:
```json
"versions": [
@@ -26,15 +26,14 @@ If you would like to specify a default version, you can do so like this:
```
- The versions dropdown will show your versions in the order you include them in
- `mint.json`.
+ The versions dropdown menu will display your versions in the same order as they appear in `mint.json`.
### Versioning Groups and Pages
-The best way to specify page versions is by adding a version value to a group in the navigation. When you specify the version of a group, that version is applied to all pages within that group.
+The recommended way to specify page versions is by adding a version value to a group in the navigation. When you specify a version for a group, that version applies to all pages within that group.
-You can also specify the version of a single page in the page metadata. Versions on individual pages always take precedence.
+You can also specify the version of individual pages in their page metadata. Individual page versions always take precedence over group versions.
```json Groups (mint.json)
@@ -57,16 +56,14 @@ version: "v2"
- While it is possible to nest versioned groups within versioned groups, it is
- not recommended. If you do take this approach, the more deeply-nested version
- takes precedence.
+ While it's technically possible to nest versioned groups within other versioned groups, we don't recommend this practice. If you do use nested versions, note that the more deeply-nested version takes precedence.
#### Versioning Tabs and Anchors
-You can hide a tab or anchor based on a version. This is useful if you have links that are only relevant in one version. Importantly, this does **not** apply the version to the pages within that anchor.
+You can hide specific tabs or anchors based on version. This is useful when certain links are only relevant to a particular version. Important: this does **not** apply the version to the pages within that anchor.
-In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors without a specified version are shown in every version.
+In your `mint.json`, simply add a `version` property to your tab or anchor. Tabs and anchors without a specified version will be shown in all versions.
```json Tabs
@@ -110,33 +107,27 @@ In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors wit
-#### Sharing Between Versions
+#### Sharing Content Between Versions
-Not _all_ content has to be hidden though! Any content without a specified version appears in every version so you don't have to duplicate content!
+Not all content needs to be version-specific. Any content without a specified version will appear in every version, eliminating the need for content duplication.
- When using localization with versioning, each version can have its own set of
- translations. This means you can have different language versions for
- different API versions, giving you full flexibility in managing both versioned
- and localized content.
+ When combining localization with versioning, each version can have its own set of translations. This allows you to maintain different language versions for different API versions, providing complete flexibility in managing both versioned and localized content.
### Troubleshooting
-Common errors and how to fix them
+Here are solutions for common versioning issues:
-
- You likely nested a version inside of another. For example, your group had version "v1" but your page had version "v2".
-
- We do not recommend nesting versions inside of each other because it's hard to maintain your docs later.
+
+ This usually happens when you've nested versions incorrectly. For example, if your group has version "v1" but a page within it has version "v2".
+ We recommend avoiding nested versions as they make documentation maintenance more difficult.
- If you add versions to your docs and the pages disappeared from your
- navigation, make sure you spelled the version the same as in your `versions`
- array in `mint.json`.
+ If pages disappear from your navigation after adding versions, verify that the version names in your page or group metadata exactly match the version names in your `versions` array in `mint.json`.
@@ -144,9 +135,18 @@ Common errors and how to fix them
### Setup
-`"versions"` in your `mint.json` can be leveraged to create different language versions by adding a `locale` value to the version. The first localization from the array serves as the default localization.
+You can use the `versions` field in your `mint.json` to create different language versions by adding a `locale` value to each version. The first localization in the array becomes the default localization.
+
+Mintlify currently supports localization in:
+- English (`en`)
+- Chinese (`cn`)
+- Spanish (`es`)
+- French (`fr`)
+- Japanese (`jp`)
+- Portuguese (`pt`)
+- German (`de`)
-We currently support localization in English (`en`), Chinese (`cn`), Spanish (`es`), French (`fr`), Japanese (`jp`), Portuguese (`pt`), and German (`de`).
+Here's an example configuration:
```json mint.json example
"versions": [
@@ -166,8 +166,7 @@ We currently support localization in English (`en`), Chinese (`cn`), Spanish (`e
```
- The versions dropdown will show your localizations in the order you include
- them in the `mint.json`.
+ The versions dropdown menu will display your localizations in the order they appear in your `mint.json` file.
-Once setup, the rest of localization is handled by the versioning setup described above.
+After completing the localization setup, you can manage your localized content using the same versioning mechanisms described above.
\ No newline at end of file
diff --git a/web-editor.mdx b/web-editor.mdx
index 0c945d94b..8945d8b6c 100644
--- a/web-editor.mdx
+++ b/web-editor.mdx
@@ -3,84 +3,80 @@ title: 'Web Editor'
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 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 several key features that integrate directly into your existing Git workflow:
+- Creating branches
+- Making pull requests
+- Creating commits
+- Viewing diffs for your current changes
-It also includes a fully editable experience for changing and adding content directly,
-even with custom components.
+It also provides a fully editable experience for changing and adding content directly, including custom components.
-If you understand git workflows and our integrations already, you can skip to [here](#editing-content).
+If you already understand Git workflows and our integrations, you can skip to [here](#editing-content).
-## Git and update workflows
+## Git and Update Workflows
-### Git basics
+### 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.
+While the Web Editor means you don't need to use GitHub or your command line to make changes, it's still helpful to understand 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
+### 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 provide several buttons that integrate with your Git workflow.
- 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
+ If you haven't already installed the Mintlify GitHub App to your GitHub account,
+ please do so. 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
+
+ When making changes to your docs, you might want to work on a branch other than main
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.
+ To do this, 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
- create a new branch by clicking the **"New Branch"** button.
+ From here, you can either switch to a different Git branch or create a new branch by clicking the **"New Branch"** button.
- 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.
+ After creating a new branch, you'll automatically switch to it. All changes you make will be on 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 reload the page, 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, always create a new branch when making changes so you can submit a pull request for review by other teammates. You may not have permissions to make changes to the main branch directly, in which case we'll help you open a pull request.
-
- In order to make a commit, you have two options, both of which appear on the top
- right of the editor:
+
+ There are two ways to make a commit, both accessible from buttons 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`.
+ directly by clicking the **"Publish"** button. Your changes will appear in your Git branch the next time you run `git pull`.
@@ -88,10 +84,10 @@ 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
- up for review, you can click the **"Publish Pull Request"** button.
+
+ If you're not on the main branch, you can:
+ - Push a commit to your branch by clicking the **"Save Changes"** button
+ - Create a pull request for review by clicking the **"Publish Pull Request"** button
@@ -100,14 +96,12 @@ integrate with your git workflow.
- This will create the pull request for you on GitHub using the branch you selected onto
- your main branch.
+ This will create the pull request on GitHub from your selected branch to the 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
- empty.
+
+ When creating a pull request, you can customize the title and description.
+ If you leave these fields empty, we'll provide a default Mintlify title.
@@ -116,31 +110,30 @@ integrate with your git workflow.
-## Editing content
+## Editing Content
-### Slash commands
+### Slash Commands
-The easiest way to add content in the editor is by using **"Slash commands"**, which are
-commands you have access to after typing `/` in the **"Visual Editor"** mode:
+The easiest way to add content is using **"Slash Commands"**. These commands are available after typing `/` in the **"Visual Editor"** mode:
-As you type, you'll see more options pop up:
+As you type, the list of available commands will filter:
-
+
-#### Content blocks
+#### Content Blocks
-Here are the types of content blocks available to add in the **"Visual Editor"**:
+Here are the types of content blocks available in the **"Visual Editor"**:
-
+
Paragraph
Headings
@@ -152,7 +145,7 @@ Here are the types of content blocks available to add in the **"Visual Editor"**
-
+
Callouts
Accordions
@@ -169,113 +162,109 @@ Here are the types of content blocks available to add in the **"Visual Editor"**
-### Adding images
+### 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.
+To add images to your page:
+1. Type `/image`
+2. Either click the **"Image"** option or press ↓ + Enter
-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 opens the image modal where you can:
+- Upload a new image
+- Use an existing image from the repository
-Uploading an image can be done through the modal:
+Upload an image through the modal:
-And you can preview an existing image before you add it.
+Preview an existing image before adding it:
-### Editing images
+### Editing Images
-In order to edit images, you just have to hover over the image to see the **"Delete"**
-and **"Edit"** buttons on the top right of the image.
+To edit images:
+1. Hover over the image
+2. Look for the **"Delete"** and **"Edit"** buttons on the top right
-Clicking the **"Edit"** button lets you edit the attributes of the image.
+Click the **"Edit"** button to modify the image 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
-using the [instructions above](#adding-images).
+To update an image with a new one that hasn't been uploaded yet:
+1. Delete the existing image
+2. Add a new one using the [instructions above](#adding-images)
-## Editor modes
+## Editor Modes
-In order to offer the most flexibility, the editor has three modes:
+The editor offers three modes for maximum flexibility:
-
+
### 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"** provides a WYSIWYG (What You See Is What You Get) interface similar to Notion.
+It shows you exactly how your content will appear on your main docs site while allowing full editing capabilities.
### 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 directly in code, similar to working in an IDE. While it offers less component auto-completion than the Visual Editor, it provides two key 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. You can edit component props (see our [limitations below](#current-limitations))
+which isn't yet available in the **"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. You can fix syntax errors that might prevent content from displaying correctly in the **"Visual Editor"** mode.
### Diff View
-The **"Diff View"** is a way to view the changes made to a specific document before
-committing it to your repository.
+The **"Diff View"** shows changes made to a document before committing to your repository. This helps you:
+- Review your content changes
+- See formatting adjustments made by the editor
-This will help you see changes you've made along with formatting changes made by
-the editor.
+## Current Limitations
-## Current limitations
-
-We do have a few current limitations in the editor that we're working to resolve.
+The editor currently has these limitations 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`
+
+ You cannot live-update your navigation based on file changes. You must manually edit the `mint.json` file when renaming, adding, or deleting files.
-
- We currently don't show any previews for custom snippets. This is on our roadmap to support
- as fully editable components.
+
+ We don't currently show previews for custom snippets. Adding support for fully editable components is on our roadmap.
-
- We currently don't show any previews for OpenAPI specs. This is on our roadmap to support
- as a read-only preview.
+
+ We don't currently show previews for OpenAPI specifications. Adding read-only preview support is on our roadmap.
## Feedback
-If you have any bug reports, feature requests, or other general feedback, we'd love to hear
-where we can improve.
+We welcome your feedback on how we can improve the Web Editor. If you have:
+- Bug reports
+- Feature requests
+- General feedback
-Email us at [support@mintlify.com](mailto:support@mintlify.com)
\ No newline at end of file
+Please email us at [support@mintlify.com](mailto:support@mintlify.com)
\ No newline at end of file