From 77fcec659c8b1583f43b1376e801f39cdf8fe250 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:23:56 +0000 Subject: [PATCH 01/10] Update docs.json --- docs.json | 1 - 1 file changed, 1 deletion(-) diff --git a/docs.json b/docs.json index 60d91773a..7200f0f3e 100644 --- a/docs.json +++ b/docs.json @@ -28,7 +28,6 @@ "index", "quickstart", "installation", - "editor", "ai-native", "migration" ] From 32a456347de51140c9a87579745d6b410912d4c4 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:24:05 +0000 Subject: [PATCH 02/10] Update docs.json --- docs.json | 1 - 1 file changed, 1 deletion(-) diff --git a/docs.json b/docs.json index 7200f0f3e..81678637a 100644 --- a/docs.json +++ b/docs.json @@ -329,7 +329,6 @@ "fr/index", "fr/quickstart", "fr/installation", - "fr/editor", "fr/ai-native", "fr/migration" ] From f734988bbe39ec5fe9a00459a535b61e450fda90 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:24:10 +0000 Subject: [PATCH 03/10] Update docs.json --- docs.json | 1 - 1 file changed, 1 deletion(-) diff --git a/docs.json b/docs.json index 81678637a..59b004d5e 100644 --- a/docs.json +++ b/docs.json @@ -629,7 +629,6 @@ "es/index", "es/quickstart", "es/installation", - "es/editor", "es/ai-native", "es/migration" ] From 73b6524e240c62d0a8a9615605c54290865359d7 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:24:16 +0000 Subject: [PATCH 04/10] Update docs.json --- docs.json | 1 - 1 file changed, 1 deletion(-) diff --git a/docs.json b/docs.json index 59b004d5e..beef0ca67 100644 --- a/docs.json +++ b/docs.json @@ -929,7 +929,6 @@ "zh/index", "zh/quickstart", "zh/installation", - "zh/editor", "zh/ai-native", "zh/migration" ] From 475532458922e0f1df9169e561e74d9216f655ae Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:24:21 +0000 Subject: [PATCH 05/10] Delete editor.mdx --- editor.mdx | 421 ----------------------------------------------------- 1 file changed, 421 deletions(-) delete mode 100644 editor.mdx diff --git a/editor.mdx b/editor.mdx deleted file mode 100644 index bae5ff72d..000000000 --- a/editor.mdx +++ /dev/null @@ -1,421 +0,0 @@ ---- -title: "Visual editor" -description: "Create, maintain, and publish documentation in your browser." -keywords: ["visual editor", "WYSIWYG", "web editor"] ---- - -Mintlify visual editor interface in light mode - -Mintlify visual editor interface in dark mode - -Access the visual editor from your [dashboard](https://dashboard.mintlify.com/editor) to manage your documentation directly in your browser. - -- **WYSIWYG editing**: Make changes to your documentation using a what-you-see-is-what-you-get (WYSIWYG) editor that shows how your content will look when published. -- **Git synchronization**: All changes automatically sync with your Git repository to maintain version control. -- **Team collaboration**: Multiple people can work on documentation simultaneously. -- **Component integration**: Add callouts, code blocks, and other components with slash commands. -- **No setup required**: Start writing immediately from your dashboard. - -## Overview - -Here is how you'll typically work in the visual editor: - - - - Create a branch or make changes directly to your deployment branch. We recommend creating a branch so that you can preview your changes before they go live. - - - Navigate to an existing file in the sidebar or create a new one using the file explorer. - - - Make changes in the visual editor. Press / - - to open the component menu. - - - Visual mode shows you how your changes will appear on your live site. Use this to verify everything looks correct. - - - If you're working on your deployment branch, publish your changes directly from the visual editor. On other branches, you'll create a pull request for review before publishing. - - - -## Editor modes - -The visual editor has two modes to accommodate different editing preferences and needs: visual mode and Markdown mode. - -Use the mode toggle in the editor toolbar to switch modes. - - - Mode toggle icons highlighted in the visual editor. - - Mode toggle icons highlighted in the visual editor. - - -### Visual mode - -Visual mode provides a WYSIWYG experience where changes that you make in the editor reflect how your published documentation will look. This mode is ideal for when you want to see how your changes will look in real-time. - - - Visual editing mode in the Mintlify visual editor - - Visual editing mode in the Mintlify visual editor - - -### Markdown mode - -Markdown mode provides direct access to the files that make up your documentation. This mode is ideal for when you need precise control over component properties or when you prefer to write in MDX syntax. - - - Markdown mode in the Mintlify visual editor - - Markdown mode in the Mintlify visual editor - - -## Manage content - -### Navigate your files - -Use the sidebar file explorer to browse your documentation files. Click on any file to open it in the editor. - -Press Command + P on macOS or Ctrl + P on Windows to search for files by name. - -### Create new pages - -Select the **Create a new file** icon in the file explorer sidebar. - - - Files menu in the visual editor - - Files menu in the visual editor in dark mode - - -Filenames are automatically appended with a `.mdx` extension. To change the file type, click the file extension. Select the file type you want from the dropdown menu. - - - File extension menu in the visual editor. - - File extension menu in the visual editor in dark mode. - - -### Rename pages - -To rename a page, click the kebab menu icon for the file you want to rename. Select **Rename** from the dropdown menu. - - - Rename page in the visual editor. - - Rename page in the visual editor in dark mode. - - -### Delete pages - -To delete a page, click the kebab menu icon for the file you want to delete. Select **Delete** from the dropdown menu. - - - Delete page in the visual editor. - - Delete page in the visual editor in dark mode. - - -### Organize your navigation - -Edit your `docs.json` file to add new pages and remove deleted pages from your site navigation. See [Navigation](/organize/navigation) for more information on how to organize pages. - -**Example: Add a Themes page to the Profile group** - -In this example, you created a new page titled Themes and you want to add it to the Profile group in your documentation. Add the path to the new page to the `pages` array of the `Profile` group in your `docs.json` file for it to appear in your site navigation. - -```json Adding a Themes page to the Profile group {18} -{ - "navigation": { - "groups": [ - { - "group": "Getting started", - "pages": [ - "index", - "quickstart", - "installation" - ] - }, - { - "group": "Profile", - "pages": [ - "settings", - "account-types", - "dashboard", - "themes" - ] - } - ] - } -} -``` - -### Edit content - -Make changes to your pages using visual mode or Markdown mode in the editor. - -In visual mode, press / to open the component menu. Add content blocks, callouts, code blocks, and other components to customize your documentation. - - - The unfurled component menu emphasized in the Mintlify visual editor - - The unfurled component menu emphasized in the Mintlify visual editor - - -In Markdown mode, you can directly edit the MDX of your pages. This can be helpful when you need to: - -- Set specific component properties -- Work with complex nested components -- Copy and paste MDX content from other sources - -See [Format text](/create/text) and [Format code](/create/code) for more information on how to write using MDX syntax. - -## Publish your changes - -The branch that you work on determines how the editor publishes your changes: - -- **Deployment branch**: Publishing updates your live site immediately. -- **Other branches**: Publishing creates a pull request so you can review changes before deploying them to production. - - - The publish button emphasized in the Mintlify visual editor - - The publish button emphasized in the Mintlify visual editor - - -If you authorize Mintlify to your GitHub user, your commits will be signed as if you had made them yourself. If not, they will be signed by the Mintlify GitHub app. - -### Pull requests and reviewing changes - -Pull requests let you propose changes from your branch so that other people can review them before merging into your live documentation. This helps ensure that your changes are correct and gives your team a chance to collaborate on content. - - - Even if you're working solo, pull requests are valuable for previewing changes and maintaining a clear history of updates. - - -#### Create a pull request - - - - Select **Save Changes** to save all changes on your branch. - - - Select **Publish Pull Request** from the editor toolbar. - - - Write a clear title and description explaining: - - - What changes you made - - Why you made them - - Any specific areas that need review - - - Select **Publish Pull Request**. The editor will provide a link to view your pull request. - - - Publish pull request button emphasized in the Mintlify visual editor - - Publish pull request button emphasized in the Mintlify visual editor - - - - -#### Review pull requests - -Once your pull request is created: - -1. **Review changes**: You and your team members can review your pull request in your Git provider like GitHub or GitLab. -2. **Leave feedback**: Add comments or request changes. -3. **Make additional changes**: Make additional changes in the visual editor. When you save changes, the editor pushes them to your pull request. -4. **Approve**: Approve the pull request when you're satisfied with the changes. -5. **Merge**: Merge the pull request when you're ready to deploy your changes to production. - -## Keyboard shortcuts - -The visual editor supports all common keyboard shortcuts such as copy, paste, undo, and select all, and the following shortcuts: - -| Command | macOS | Windows | -| :------------------------------- | :--------------------------------------------------- | :------------------------------------------------------- | -| **Search files** | Cmd + P | Control + P | -| **Add link to highlighted text** | Cmd + K | Control + K | -| **Add line break** | Cmd + Enter | Control + Enter | -| **Bold** | Cmd + B | Control + B | -| **Italic** | Cmd + I | Control + I | -| **Underline** | Cmd + U | Control + U | -| **Strikethrough** | Cmd + Shift + S | Control + Shift + S | -| **Code** | Cmd + E | Control + E | -| **Normal text** | Cmd + Alt + 0 | Control + Alt + 0 | -| **Heading 1** | Cmd + Alt + 1 | Control + Alt + 1 | -| **Heading 2** | Cmd + Alt + 2 | Control + Alt + 2 | -| **Heading 3** | Cmd + Alt + 3 | Control + Alt + 3 | -| **Heading 4** | Cmd + Alt + 4 | Control + Alt + 4 | -| **Ordered list** | Cmd + Shift + 7 | Control + Shift + 7 | -| **Unordered list** | Cmd + Shift + 8 | Control + Shift + 8 | -| **Blockquote** | Cmd + Shift + B | Control + Shift + B | -| **Subscript** | Cmd + , | Control + , | -| **Superscript** | Cmd + . | Control + . | - -## Troubleshooting - -Find solutions to common issues you might encounter while using the visual editor. - - - - **Possible causes:** - - - Deployment is still in progress - - Browser caching issues - - Build or deployment errors - - **Solutions:** - - 1. Check deployment status in your dashboard. - 2. Hard refresh your browser (Ctrl - - + F5 - - or Cmd - - + Shift - - + R - - ) - 3. Clear your browser cache. - - - **Possible causes:** - - - Insufficient permissions to the Git repository - - Authentication issues with your Git provider - - **Solutions:** - - 1. Verify you have correct access to the repository. - 2. Check if your Git integration is properly configured. - 3. Review the [Editor Permissions](/dashboard/permissions) documentation. - - - **Possible causes:** - - - Network connectivity problems - - Large documentation repositories - - **Solutions:** - - 1. Check your internet connection. - 2. Refresh the page. - 3. Contact support if the issue persists. - - - **Possible causes:** - - - Invalid MDX syntax in files - - Missing or corrupted files - - Large file sizes causing timeouts - - **Solutions:** - - 1. Check the file syntax for MDX formatting errors - 2. Verify the file exists in your repository. - - - -## Next steps - -- Learn fundamental [Git concepts](/guides/git-concepts) -- Learn best practices for collaborating with [branches](/guides/branches) \ No newline at end of file From 022bfecd81ae7405e6e4f9e62fb4c5740df0164f Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:26:19 +0000 Subject: [PATCH 06/10] Update editor.mdx --- editor.mdx | 421 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 421 insertions(+) create mode 100644 editor.mdx diff --git a/editor.mdx b/editor.mdx new file mode 100644 index 000000000..d1f8ea49a --- /dev/null +++ b/editor.mdx @@ -0,0 +1,421 @@ +--- +title: "Visual editor" +description: "Create, maintain, and publish documentation in your browser." +keywords: ["visual editor", "WYSIWYG", "web editor"] +--- + +Mintlify visual editor interface in light mode + +Mintlify visual editor interface in dark mode + +Access the visual editor from your [dashboard](https://dashboard.mintlify.com/editor) to manage your documentation directly in your browser. + +- **WYSIWYG editing**: Make changes to your documentation using a what-you-see-is-what-you-get (WYSIWYG) editor that shows how your content will look when published. +- **Git synchronization**: All changes automatically sync with your Git repository to maintain version control. +- **Team collaboration**: Multiple people can work on documentation simultaneously. +- **Component integration**: Add callouts, code blocks, and other components with slash commands. +- **No setup required**: Start writing immediately from your dashboard. + +## Overview + +Here is how you'll typically work in the visual editor: + + + + Create a branch or make changes directly to your deployment branch. We recommend creating a branch so that you can preview your changes before they go live. + + + Navigate to an existing file in the sidebar or create a new one using the file explorer. + + + Make changes in the visual editor. Press / + + to open the component menu. + + + Visual mode shows you how your changes will appear on your live site. Use this to verify everything looks correct. + + + If you're working on your deployment branch, publish your changes directly from the visual editor. On other branches, you'll create a pull request for review before publishing. + + + +## Editor modes + +The visual editor has two modes to accommodate different editing preferences and needs: visual mode and Markdown mode. + +Use the mode toggle in the editor toolbar to switch modes. + + + Mode toggle icons highlighted in the visual editor. + + Mode toggle icons highlighted in the visual editor. + + +### Visual mode + +Visual mode provides a WYSIWYG experience where changes that you make in the editor reflect how your published documentation will look. This mode is ideal for when you want to see how your changes will look in real-time. + + + Visual editing mode in the Mintlify visual editor + + Visual editing mode in the Mintlify visual editor + + +### Markdown mode + +Markdown mode provides direct access to the files that make up your documentation. This mode is ideal for when you need precise control over component properties or when you prefer to write in MDX syntax. + + + Markdown mode in the Mintlify visual editor + + Markdown mode in the Mintlify visual editor + + +## Manage content + +### Navigate your files + +Use the sidebar file explorer to browse your documentation files. Click on any file to open it in the editor. + +Press Command + P on macOS or Ctrl + P on Windows to search for files by name. + +### Create new pages + +Select the **Create a new file** icon in the file explorer sidebar. + + + Files menu in the visual editor + + Files menu in the visual editor in dark mode + + +Filenames are automatically appended with a `.mdx` extension. To change the file type, click the file extension. Select the file type you want from the dropdown menu. + + + File extension menu in the visual editor. + + File extension menu in the visual editor in dark mode. + + +### Rename pages + +To rename a page, click the kebab menu icon for the file you want to rename. Select **Rename** from the dropdown menu. + + + Rename page in the visual editor. + + Rename page in the visual editor in dark mode. + + +### Delete pages + +To delete a page, click the kebab menu icon for the file you want to delete. Select **Delete** from the dropdown menu. + + + Delete page in the visual editor. + + Delete page in the visual editor in dark mode. + + +### Organize your navigation + +Edit your `docs.json` file to add new pages and remove deleted pages from your site navigation. See [Navigation](/organize/navigation) for more information on how to organize pages. + +**Example: Add a Themes page to the Profile group** + +In this example, you created a new page titled Themes and you want to add it to the Profile group in your documentation. Add the path to the new page to the `pages` array of the `Profile` group in your `docs.json` file for it to appear in your site navigation. + +```json Adding a Themes page to the Profile group {18} +{ + "navigation": { + "groups": [ + { + "group": "Getting started", + "pages": [ + "index", + "quickstart", + "installation" + ] + }, + { + "group": "Profile", + "pages": [ + "settings", + "account-types", + "dashboard", + "themes" + ] + } + ] + } +} +``` + +### Edit content + +Make changes to your pages using visual mode or Markdown mode in the editor. + +In visual mode, press / to open the component menu. Add content blocks, callouts, code blocks, and other components to customize your documentation. + + + The unfurled component menu emphasized in the Mintlify visual editor + + The unfurled component menu emphasized in the Mintlify visual editor + + +In Markdown mode, you can directly edit the MDX of your pages. This can be helpful when you need to: + +- Set specific component properties +- Work with complex nested components +- Copy and paste MDX content from other sources + +See [Format text](/create/text) and [Format code](/create/code) for more information on how to write using MDX syntax. + +## Publish your changes + +The branch that you work on determines how the editor publishes your changes: + +- **Deployment branch**: Publishing updates your live site immediately. +- **Other branches**: Publishing creates a pull request so you can review changes before deploying them to production. + + + The publish button emphasized in the Mintlify visual editor + + The publish button emphasized in the Mintlify visual editor + + +If you authorize Mintlify to your GitHub user, your commits will be signed as if you had made them yourself. If not, they will be signed by the Mintlify GitHub app. + +### Pull requests and reviewing changes + +Pull requests let you propose changes from your branch so that other people can review them before merging into your live documentation. This helps ensure that your changes are correct and gives your team a chance to collaborate on content. + + + Even if you're working solo, pull requests are valuable for previewing changes and maintaining a clear history of updates. + + +#### Create a pull request + + + + Select **Save Changes** to save all changes on your branch. + + + Select **Publish Pull Request** from the editor toolbar. + + + Write a clear title and description explaining: + + - What changes you made + - Why you made them + - Any specific areas that need review + + + Select **Publish Pull Request**. The editor will provide a link to view your pull request. + + + Publish pull request button emphasized in the Mintlify visual editor + + Publish pull request button emphasized in the Mintlify visual editor + + + + +#### Review pull requests + +Once your pull request is created: + +1. **Review changes**: You and your team members can review your pull request in your Git provider like GitHub or GitLab. +2. **Leave feedback**: Add comments or request changes. +3. **Make additional changes**: Make additional changes in the visual editor. When you save changes, the editor pushes them to your pull request. +4. **Approve**: Approve the pull request when you're satisfied with the changes. +5. **Merge**: Merge the pull request when you're ready to deploy your changes to production. + +## Keyboard shortcuts + +The visual editor supports all common keyboard shortcuts such as copy, paste, undo, and select all, and the following shortcuts: + +| Command | macOS | Windows | +| :------------------------------- | :--------------------------------------------------- | :------------------------------------------------------- | +| **Search files** | Cmd + P | Control + P | +| **Add link to highlighted text** | Cmd + K | Control + K | +| **Add line break** | Cmd + Enter | Control + Enter | +| **Bold** | Cmd + B | Control + B | +| **Italic** | Cmd + I | Control + I | +| **Underline** | Cmd + U | Control + U | +| **Strikethrough** | Cmd + Shift + S | Control + Shift + S | +| **Code** | Cmd + E | Control + E | +| **Normal text** | Cmd + Alt + 0 | Control + Alt + 0 | +| **Heading 1** | Cmd + Alt + 1 | Control + Alt + 1 | +| **Heading 2** | Cmd + Alt + 2 | Control + Alt + 2 | +| **Heading 3** | Cmd + Alt + 3 | Control + Alt + 3 | +| **Heading 4** | Cmd + Alt + 4 | Control + Alt + 4 | +| **Ordered list** | Cmd + Shift + 7 | Control + Shift + 7 | +| **Unordered list** | Cmd + Shift + 8 | Control + Shift + 8 | +| **Blockquote** | Cmd + Shift + B | Control + Shift + B | +| **Subscript** | Cmd + , | Control + , | +| **Superscript** | Cmd + . | Control + . | + +## Troubleshooting + +Find solutions to common issues you might encounter while using the visual editor. + + + + **Possible causes:** + + - Deployment is still in progress + - Browser caching issues + - Build or deployment errors + + **Solutions:** + + 1. Check deployment status in your dashboard. + 2. Hard refresh your browser (Ctrl + + + F5 + + or Cmd + + + Shift + + + R + + ) + 3. Clear your browser cache. + + + **Possible causes:** + + - Insufficient permissions to the Git repository + - Authentication issues with your Git provider + + **Solutions:** + + 1. Verify you have correct access to the repository. + 2. Check if your Git integration is properly configured. + 3. Review the [Editor Permissions](/dashboard/permissions) documentation. + + + **Possible causes:** + + - Network connectivity problems + - Large documentation repositories + + **Solutions:** + + 1. Check your internet connection. + 2. Refresh the page. + 3. Contact support if the issue persists. + + + **Possible causes:** + + - Invalid MDX syntax in files + - Missing or corrupted files + - Large file sizes causing timeouts + + **Solutions:** + + 1. Check the file syntax for MDX formatting errors + 2. Verify the file exists in your repository. + + + +## Next steps + +- Learn fundamental [Git concepts](/guides/git-concepts) +- Learn best practices for collaborating with [branches](/guides/branches) From 9cdec7e2c022e1c4bf8d52c6b3e9af129f02c45c Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:26:30 +0000 Subject: [PATCH 07/10] Update docs.json --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index beef0ca67..ae1cdfe6c 100644 --- a/docs.json +++ b/docs.json @@ -28,6 +28,7 @@ "index", "quickstart", "installation", + "editor", "ai-native", "migration" ] From 43caeeaf2beda273d47f2bbf8308e73574d4b0b9 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:26:36 +0000 Subject: [PATCH 08/10] Update docs.json --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index ae1cdfe6c..3c5829550 100644 --- a/docs.json +++ b/docs.json @@ -330,6 +330,7 @@ "fr/index", "fr/quickstart", "fr/installation", + "fr/editor", "fr/ai-native", "fr/migration" ] From 14981b081cf4a9b693d53a92d98be69568ab5cd2 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:26:37 +0000 Subject: [PATCH 09/10] Update docs.json --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index 3c5829550..d3a5ddf58 100644 --- a/docs.json +++ b/docs.json @@ -631,6 +631,7 @@ "es/index", "es/quickstart", "es/installation", + "es/editor", "es/ai-native", "es/migration" ] From c5522eaee49a4ec849d376e4fbe43dd211c20790 Mon Sep 17 00:00:00 2001 From: "mintlify-development[bot]" <109878554+mintlify-development[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 02:26:48 +0000 Subject: [PATCH 10/10] Update docs.json --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index d3a5ddf58..60d91773a 100644 --- a/docs.json +++ b/docs.json @@ -932,6 +932,7 @@ "zh/index", "zh/quickstart", "zh/installation", + "zh/editor", "zh/ai-native", "zh/migration" ]