
- 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:1
Choose your branch
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.
2
Open your file
Navigate to an existing file in the sidebar or create a new one using the file explorer.
3
Edit your content
Make changes in the visual editor. Press / to open the component menu.
4
Preview your changes
Visual mode shows you how your changes will appear on your live site. Use this to verify everything looks correct.
5
Publish your changes
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.
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.
Markdown mode
Markdown mode provides direct access to the underlyingMDX
code of your documentation. This mode is ideal for when you need precise control over component properties or when you prefer to write in Markdown syntax.

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.
.mdx
extension. To change the file type, click the file extension. Select the file type you want from the dropdown menu.

Rename pages
To rename a page, click the kebab menu icon for the file you want to rename. Select Rename from the dropdown menu.
Delete pages
To delete a page, click the kebab menu icon for the file you want to delete. Select Delete from the dropdown menu.
Organize your navigation
Edit yourdocs.json
file to add new pages and remove deleted pages from your site navigation. See 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.
Adding a Themes page to the Profile group
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.
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
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.

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
1
Save your work
Select Save Changes to save all changes on your branch.
2
Create the pull request
Select Publish Pull Request from the editor toolbar.
3
Add a title and description
Write a clear title and description explaining:
- What changes you made
- Why you made them
- Any specific areas that need review
4
Create and share
Select Publish Pull Request. The editor will provide a link to view your pull request.

Review pull requests
Once your pull request is created:- Review changes: You and your team members can review your pull request in your Git provider like GitHub or GitLab.
- Leave feedback: Add comments or request changes.
- Make additional changes: Make additional changes in the visual editor. When you save changes, the editor pushes them to your pull request.
- Approve: Approve the pull request when you’re satisfied with the changes.
- 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.Changes not appearing after publishing
Changes not appearing after publishing
Possible causes:
- Deployment is still in progress
- Browser caching issues
- Build or deployment errors
- Check deployment status in your dashboard.
- Hard refresh your browser (Ctrl + F5 or Cmd + Shift + R)
- Clear your browser cache.
Permission errors when publishing
Permission errors when publishing
Possible causes:
- Insufficient permissions to the Git repository
- Authentication issues with your Git provider
- Verify you have correct access to the repository.
- Check if your Git integration is properly configured.
- Review the Editor Permissions documentation.
Editor loading issues
Editor loading issues
Possible causes:
- Network connectivity problems
- Large documentation repositories
- Check your internet connection.
- Refresh the page.
- Contact support if the issue persists.
Files not loading or showing errors
Files not loading or showing errors
Possible causes:
- Invalid MDX syntax in files
- Missing or corrupted files
- Large file sizes causing timeouts
- Check the file syntax for MDX formatting errors
- Verify the file exists in your repository.
Next steps
- Learn fundamental Git concepts
- Learn best practices for collaborating with branches