diff --git a/core-concepts/navigation.mdx b/core-concepts/navigation.mdx
index 31cf49b2..1d67bacb 100644
--- a/core-concepts/navigation.mdx
+++ b/core-concepts/navigation.mdx
@@ -50,8 +50,16 @@ Pages are the most fundamental navigation component.
@@ -78,8 +86,16 @@ Groups allow you to group your pages. Groups can also be nested within each othe
@@ -115,8 +131,16 @@ documentation.
@@ -155,8 +179,16 @@ Anchors are another way to section your content. They show up on top of your sid
@@ -175,7 +207,7 @@ While not required, we highly recommend that you set an `icon` field as well.
"development",
"navigation"
]
- }
+ },
{
"anchor": "API References",
"icon": "sqaure-terminal",
@@ -184,7 +216,7 @@ While not required, we highly recommend that you set an `icon` field as well.
"api-reference/post",
"api-reference/delete"
]
- }
+ },
{
"anchor": "Blog",
"href": "https://external-link.com/blog"
@@ -201,8 +233,16 @@ Dropdowns show up in the same place as anchors, but are consolidated into a sing
@@ -239,15 +279,22 @@ While not required, we also recommend that you set an icon for each dropdown ite
---
-
### Versions
Versions can be leveraged to partition your navigation into different versions.
@@ -286,29 +333,67 @@ Languages can be leveraged to partition your navigation into different languages
We currently support the following languages:
-
-} horizontal />
-} horizontal/>
-} horizontal/>
-} horizontal />
-} horizontal />
-} horizontal />
-} horizontal />
-} horizontal />
-} horizontal />
-} horizontal />
-} horizontal />
-} horizontal />
-} horizontal />
-} horizontal />
-} horizontal />
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
+ } horizontal>
+
+
```json
@@ -383,6 +468,7 @@ This way, you can create a very complex navigation structure that is easy to man
}
```
+
```json Tabs
{
"navigation": {
@@ -462,5 +548,4 @@ This way, you can create a very complex navigation structure that is easy to man
}
```
-
\ No newline at end of file
diff --git a/editor.mdx b/editor.mdx
index 487245de..fd31dab3 100644
--- a/editor.mdx
+++ b/editor.mdx
@@ -1,320 +1,416 @@
---
-title: 'Web Editor'
-description: 'Build your documentation using the Mintlify Web Editor'
-icon: 'mouse-pointer-2'
+title: "Web Editor"
+description: "Edit your docs directly from the dashboard with live previews."
+icon: "mouse-pointer-2"
---
-
-
+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.
+
+It also includes a fully editable experience for changing and adding content directly,
+even with custom [components](/index).
+
+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.
+
+Git terminology:
+
+- **Repository**: The folder in which 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.
+
+### Making updates
+
+In order to make updates to your docs, we include a few buttons specifically to
+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
+ the app in the [GitHub App page](https://dashboard.mintlify.com/settings/organization/github-app)
+ page of the dashboard.
+
+
+
+
+ In order 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.
+
+
+ 
+
+ 
+
+ 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.
+
+
+ 
+
+ 
+
+ 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.
+
+
+ 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
+ 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`.
+
+
+ 
+
+ 
+
+
+
+ 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.
+
+
+ 
+
+ 
+
+
+
+ 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
+ empty.
+
+
+ 
+
+ 
+
+
+
+
+## Editing content
+
+### 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:
-## Introduction
+
+ 
-The Web Editor provides a visual interface for creating and managing your documentation without requiring local development tools or command-line knowledge.
+ 
+
-It offers a **What-You-See-Is-What-You-Get (WYSIWYG)** experience while maintaining synchronization with your Git repository, making it the perfect solution for team collaboration and quick documentation updates.
+As you type, you'll see more options pop up:
-## Web Editor vs. CLI
+
+ 
-The Web Editor is a visual editor that allows you to create and manage your documentation directly in the browser.
+ 
+
-The CLI is a command-line tool that allows you to create and manage your documentation locally. It's the recommended workflow for developers who want to integrate documentation into their code workflows.
+#### Content blocks
-Both workflows are fully integrated with your Git repository, so you can use them interchangeably.
+Here are the types of content blocks available to add in the **"Visual Editor"**:
-
- **Tip:** For teams with mixed technical abilities, we recommend using both approaches: developers can use the CLI workflow while content writers and product managers can use the Web Editor.
-
+
+
+
+
+ Paragraph
+
+
+
+ Headings
+
+
+
+ Bullet List
+
+
+
+ Numbered List
+
+
+
+ Table
+
+
+
+ Image
+
+
+
+ Blockquote
+
+
+
+
+
+
+ Callouts
+
+
+
+ Accordions
+
+
+
+ Accordion Group
+
+
+
+ Cards
+
+
+
+ Card Group
+
+
+
+ Code Block
+
+
+
+ Code Group
+
+
+
+ Tabs
+
+
+
+ Steps
+
+
+
+ Frames
+
+
+
+ Update
+
+
+
+
+
+### Adding images
-## Editor Modes
+You can add images to your page by typing `/image` and either clicking on the **"Image"**
+option or hitting ↓
-The Web Editor offers two distinct modes to accommodate different editing preferences and needs.
+ \+ Enter
-You can switch between modes at any time using the toggle in the top right corner of the editor toolbar.
+ 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.
- 
- 
-### Visual Mode
-
-Visual Mode provides a rich WYSIWYG experience where you can see exactly how your documentation will appear as you create it.
+Uploading an image can be done through the modal:
- 
- 
-### Markdown Mode
-
-Markdown Mode provides direct access to the underlying MDX code of your documentation. This mode is preferable when you need precise control over component properties or when you're comfortable with Markdown/MDX syntax.
+And you can preview an existing image before you add it.
- 
- 
-## Component Menu
-
-Unlike the CLI where you need to know the exact syntax to add a component, the Web Editor makes it easy to add various content blocks through its dropdown menu system.
+### Editing images
-To access the component menu, press the `/` key.
+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.
- 
- 
-### Available Components
-
-The component menu gives you access to all supported elements and components, including:
-
-
-
- Text, headings, blockquotes
-
-
- Ordered and unordered lists
-
-
- Tabs, accordions, cards
-
-
- Images, videos, frames
-
-
- Columns, grids
-
-
- Code blocks
-
-
-
-## Making Changes
-
-The Web Editor provides an intuitive interface for making changes.
-
-### Creating and Editing Files
-
-1. **Browse Files**: Use the sidebar file explorer to navigate through your documentation structure
-2. **Open a File**: Click on any file to open it in the editor
-3. **Make Changes**: Edit the content using Visual or Markdown mode
-4. **Preview Changes**: See how your changes will appear in real-time
-5. **Save Changes**: Changes are automatically saved as drafts
-
-## Publishing
-
-When you're ready to make your changes live, click the "Publish" button in the top-right corner to publish your changes.
+Clicking the **"Edit"** button lets you edit the attributes of the image.
- 
- 
-After publishing, your changes will be deployed to your production site.
-
-
- Publishing directly updates your configured deployment branch. For collaborative workflows, consider using branches and pull requests instead.
-
-
-## Branches
-
-Branches allow you to work on documentation changes without affecting the main version until you're ready.
-
-### Creating a Branch
-
-1. Click on the branch name in the editor toolbar (usually shows `main` by default)
-2. Select "Create a new branch"
-3. Enter a descriptive name for your branch
-4. Click "Create Branch"
-
-### Switching Branches
-
-To switch branches, you can click on the current branch name in the editor toolbar and select the branch you want to switch to from the dropdown menu.
+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).
-
- Use branches for significant updates, new sections, or when multiple team members are working on different parts of the documentation simultaneously.
-
+## Editor modes
-When you are in a branch, you can make and save changes by clicking the "Save Changes" button in the top-right corner. These changes will be saved to the branch as "commits".
+In order to offer the most flexibility, the editor has three modes:
-## Creating Pull Requests
-
-Pull requests provide a way to review changes before they're merged into your main documentation.
-
-### Creating a Pull Request
-
-1. Make your changes on a feature branch
-2. Click the "Create Pull Request" button in the top-right corner
-3. Add a title and description for your pull request
-4. Click "Create Pull Request"
-
-
- 
+
- 
-### Reviewing Pull Requests
-
-Pull requests can be reviewed directly in your Git platform (GitHub, GitLab).
-
-After the pull request is created, you can see the preview deployment of the changes.
-
-Upon approval, the pull request can be merged into your main branch and the changes will be deployed to your production site.
+### Visual Editor
-## Git Synchronization
+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 Web Editor seamlessly integrates with your Git repository, ensuring that all changes are properly versioned and tracked.
+### Source Editor
-### How Git Sync Works
+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.
-1. **Authentication**: The Web Editor connects to your Git repository through our [GitHub App](/settings/github) or [GitLab integration](/settings/gitlab).
+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.
+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. **Automatic Fetching**: When you open the editor, it automatically fetches the latest content from your repository's main branch.
+### Diff View
-3. **Change Tracking**: As you make edits in the Web Editor, changes are tracked and can be committed to your repository.
+The **"Diff View"** is a way to view the changes made to a specific document before
+committing it to your repository.
-4. **Branching**: Changes can be made directly to your main branch or to a separate feature branch, depending on your workflow preferences.
+This will help you see changes you've made along with formatting changes made by
+the editor.
-5. **Pull Requests**: For collaborative workflows, you can create pull requests directly from the Web Editor.
+## Current limitations
-## Git Terminology
-
-While not necessary, understanding the following terms will help you work more effectively with the Web Editor.
-
-The following terms are used in the Web Editor and are also used in the Git workflow.
+We do have a few current limitations in the editor that we're working to resolve.
-
-
-
-A repository (or "repo") is where your documentation files are stored, along with their revision history. The Web Editor connects to your Git repository to fetch and store documentation content.
-
-
-
-
-
-A commit is a snapshot of changes to your documentation at a specific point in time. When you publish changes in the Web Editor, you're creating a commit in your Git repository.
-
-
-
-
-
-A branch is a parallel version of your documentation that allows you to work on changes without affecting the main version. The Web Editor allows you to create and switch between branches.
-
-
-
-
-
-A pull request (PR) is a proposal to merge changes from one branch into another, typically from a feature branch into the main branch. PRs facilitate review and discussion before changes are incorporated.
-
-
-
-
-
-A diff (or difference) shows the specific changes between two versions of a file. When reviewing pull requests, diffs highlight what has been added, removed, or modified.
-
-
-
+
+ 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 `docs.json`
+
+
+ We currently don't show any 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
+ as a read-only preview.
+
-## Troubleshooting
-
-Here are solutions to common issues you might encounter with the Web Editor.
-
-
-
+## Feedback
-**Possible causes:**
-- Deployment is still in progress
-- Caching issues in your browser
+If you have any bug reports, feature requests, or other general feedback, we'd love to hear
+where we can improve.
-**Solutions:**
-1. Check deployment status in your Mintlify Dashboard
-2. Try hard refreshing 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](/advanced/dashboard/permissions) documentation
-
-
-
-
-
-**Possible causes:**
-- Network connectivity problems
-- Large documentation repositories
-
-**Solutions:**
-1. Check your internet connection
-2. Refresh the page and try again
-3. Contact support if the issue persists
-
-
-
+Email us at [support@mintlify.com](mailto:support@mintlify.com)
\ No newline at end of file
- 
+ 
- 
+ 
- 
+ 
- 
+ 
- 
+ 
- 
+ 
- 
+