Skip to content

Commit e8eacb6

Browse files
ethanpalmethanpalm
committed
consolidate editor content
1 parent 7563c9f commit e8eacb6

File tree

1 file changed

+385
-0
lines changed

1 file changed

+385
-0
lines changed

‎editor.mdx‎

Lines changed: 385 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,385 @@
1+
---
2+
title: "Visual editor"
3+
description: "Create, maintain, and publish documentation in your browser"
4+
---
5+
6+
<img
7+
className="block dark:hidden my-0 pointer-events-none"
8+
src="/images/editor/editor-light.png"
9+
alt="Mintlify visual editor interface in light mode"
10+
/>
11+
12+
<img
13+
className="hidden dark:block my-0 pointer-events-none"
14+
src="/images/editor/editor-dark.png"
15+
alt="Mintlify visual editor interface in dark mode"
16+
/>
17+
18+
Access the visual editor from your [dashboard](https://dashboard.mintlify.com/editor) to manage your documentation directly in your browser.
19+
20+
- **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.
21+
- **Git synchronization**: All changes automatically sync with your Git repository to maintain version control.
22+
- **Team collaboration**: Multiple people can work on documentation simultaneously.
23+
- **Component integration**: Add callouts, code blocks, and other components with slash commands.
24+
- **No setup required**: Start writing immediately from your dashboard.
25+
26+
## Overview
27+
28+
Here is how you'll typically work in the visual editor:
29+
30+
<Steps>
31+
<Step title="Choose your branch">
32+
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. Learn more about [working with branches](/guides/branches).
33+
</Step>
34+
<Step title="Open your file">
35+
Navigate to an existing file in the sidebar or create a new one using the file explorer.
36+
</Step>
37+
<Step title="Edit your content">
38+
Make changes in the visual editor. Press <kbd>/</kbd> to open the component menu.
39+
</Step>
40+
<Step title="Preview your changes">
41+
Visual mode shows you how your changes will appear on your live site. Use this to verify everything looks correct.
42+
</Step>
43+
<Step title="Publish your changes">
44+
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.
45+
</Step>
46+
</Steps>
47+
48+
## Editor modes
49+
50+
The visual editor has two modes to accommodate different editing preferences and needs: visual mode and Markdown mode.
51+
52+
Use the mode toggle in the editor toolbar to switch modes.
53+
54+
<Frame>
55+
<img
56+
src="/images/editor/mode-toggle-light.png"
57+
alt="Mode toggle icons highlighted in the visual editor."
58+
className="block dark:hidden"
59+
/>
60+
<img
61+
src="/images/editor/mode-toggle-dark.png"
62+
alt="Mode toggle icons highlighted in the visual editor."
63+
className="hidden dark:block"
64+
/>
65+
</Frame>
66+
67+
### Visual mode
68+
69+
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.
70+
71+
<Frame>
72+
<img
73+
src="/images/editor/visual-mode-light.png"
74+
alt="Visual editing mode in the Mintlify visual editor"
75+
className="block dark:hidden"
76+
/>
77+
<img
78+
src="/images/editor/visual-mode-dark.png"
79+
alt="Visual editing mode in the Mintlify visual editor"
80+
className="hidden dark:block"
81+
/>
82+
</Frame>
83+
84+
### Markdown mode
85+
86+
Markdown mode provides direct access to the underlying `MDX` 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.
87+
88+
<Frame>
89+
<img
90+
src="/images/editor/markdown-mode-light.png"
91+
alt="Markdown mode in the Mintlify visual editor"
92+
className="block dark:hidden"
93+
/>
94+
<img
95+
src="/images/editor/markdown-mode-dark.png"
96+
alt="Markdown mode in the Mintlify visual editor"
97+
className="hidden dark:block"
98+
/>
99+
</Frame>
100+
101+
## Manage content
102+
103+
### Navigate your files
104+
105+
Use the sidebar file explorer to browse your documentation files. Click on any file to open it in the editor.
106+
107+
Press <kbd>Command</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>P</kbd> on Windows) to search for files by name.
108+
109+
### Create new pages
110+
111+
Select the **Create a new file** icon in the file explorer sidebar.
112+
113+
<Frame>
114+
<img
115+
src="/images/editor/files-menu-light.png"
116+
className="block dark:hidden rounded-2xl border border-gray-100 shadow-lg"
117+
style={{
118+
width: '268px',
119+
height: 'auto',
120+
}}
121+
alt="Files menu in the visual editor"/>
122+
<img
123+
src="/images/editor/files-menu-dark.png"
124+
className="hidden dark:block rounded-2xl border border-white/10 shadow-lg"
125+
style={{
126+
width: '268px',
127+
height: 'auto',
128+
}}
129+
alt="Files menu in the visual editor in dark mode"/>
130+
</Frame>
131+
132+
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.
133+
134+
<Frame>
135+
<img
136+
src="/images/editor/file-type-light.png"
137+
className="block dark:hidden"
138+
alt="File extension menu in the visual editor."/>
139+
<img
140+
src="/images/editor/file-type-dark.png"
141+
className="hidden dark:block"
142+
alt="File extension menu in the visual editor in dark mode."/>
143+
</Frame>
144+
145+
### Rename pages
146+
147+
To rename a page, click the kebab menu icon for the file you want to rename. Select **Rename** from the dropdown menu.
148+
149+
<Frame>
150+
<img
151+
src="/images/editor/rename-light.png"
152+
className="block dark:hidden"
153+
alt="Rename page in the visual editor."/>
154+
<img
155+
src="/images/editor/rename-dark.png"
156+
className="hidden dark:block"
157+
alt="Rename page in the visual editor in dark mode."/>
158+
</Frame>
159+
160+
### Delete pages
161+
162+
To delete a page, click the kebab menu icon for the file you want to delete. Select **Delete** from the dropdown menu.
163+
164+
<Frame>
165+
<img
166+
src="/images/editor/delete-page-light.png"
167+
className="block dark:hidden"
168+
alt="Delete page in the visual editor."/>
169+
<img
170+
src="/images/editor/delete-page-dark.png"
171+
className="hidden dark:block"
172+
alt="Delete page in the visual editor in dark mode."/>
173+
</Frame>
174+
175+
176+
### Organize your navigation
177+
178+
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.
179+
180+
**Example: Add a Themes page to the Profile group**
181+
182+
Imagine you wrote 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 like in the following example.
183+
184+
```json title="Adding a Themes page to the Profile group" highlight="18"
185+
{
186+
"navigation": {
187+
"groups": [
188+
{
189+
"group": "Getting started",
190+
"pages": [
191+
"index",
192+
"quickstart",
193+
"installation"
194+
]
195+
},
196+
{
197+
"group": "Profile",
198+
"pages": [
199+
"settings",
200+
"account-types",
201+
"dashboard",
202+
"themes"
203+
]
204+
}
205+
]
206+
}
207+
}
208+
```
209+
210+
### Edit content
211+
212+
Make changes to your pages using visual mode or Markdown mode in the editor.
213+
214+
In visual mode, press <kbd>/</kbd> to open the component menu. Add content blocks, callouts, code blocks, and other components to customize your documentation.
215+
216+
<Frame>
217+
<img
218+
src="/images/editor/component-menu-light.png"
219+
alt="The unfurled component menu emphasized in the Mintlify visual editor"
220+
className="block dark:hidden"
221+
/>
222+
<img
223+
src="/images/editor/component-menu-dark.png"
224+
alt="The unfurled component menu emphasized in the Mintlify visual editor"
225+
className="hidden dark:block"
226+
/>
227+
</Frame>
228+
229+
In Markdown mode, you directly edit the `MDX` of your pages. This can be helpful when you need to:
230+
231+
- Set specific component properties
232+
- Work with complex nested components
233+
- Copy and paste `MDX` content from other sources
234+
235+
See [Format text](/create/text) and [Format code](/create/code) for more information on how to write using Markdown syntax.
236+
237+
## Publish your changes
238+
239+
Your changes are published based on the branch you are working on:
240+
241+
* **Deployment branch**: Publishing updates your live site immediately.
242+
* **Other branches**: Publishing creates a pull request so you can review changes before they are deployed to production.
243+
244+
<Frame>
245+
<img
246+
src="/images/editor/publish-flow-light.png"
247+
alt="The publish button emphasized in the Mintlify visual editor"
248+
className="block dark:hidden"
249+
/>
250+
<img
251+
src="/images/editor/publish-flow-dark.png"
252+
alt="The publish button emphasized in the Mintlify visual editor"
253+
className="hidden dark:block"
254+
/>
255+
</Frame>
256+
257+
### Pull requests and reviewing changes
258+
259+
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.
260+
261+
<Tip>
262+
Even if you're working solo, pull requests are valuable for previewing changes and maintaining a clear history of updates.
263+
</Tip>
264+
265+
#### Create a pull request
266+
267+
<Steps>
268+
<Step title="Save your work">
269+
Make sure all your changes are saved on your branch using **Save Changes**.
270+
</Step>
271+
<Step title="Create the pull request">
272+
Select **Publish Pull Request** in the top-right corner of the editor.
273+
</Step>
274+
<Step title="Add a title and description">
275+
Write a clear title and description explaining:
276+
- What changes you made
277+
- Why you made them
278+
- Any specific areas that need review
279+
</Step>
280+
<Step title="Create and share">
281+
Select **Publish Pull Request**. The editor will provide a link to view your pull request.
282+
283+
<Frame>
284+
<img
285+
src="/images/editor/pull-request-light.png"
286+
alt="Publish pull request button emphasized in the Mintlify visual editor"
287+
className="block dark:hidden"
288+
/>
289+
<img
290+
src="/images/editor/pull-request-dark.png"
291+
alt="Publish pull request button emphasized in the Mintlify visual editor"
292+
className="hidden dark:block"
293+
/>
294+
</Frame>
295+
</Step>
296+
</Steps>
297+
298+
#### Review pull requests
299+
300+
Once your pull request is created:
301+
302+
1. **Review changes**: You and your team members can review your pull request in your Git provider like GitHub or GitLab.
303+
2. **Leave feedback**: Add comments or request changes.
304+
3. **Make additional changes**: Make additional changes in the visual editor. When you save changes, the editor pushes them to your pull request.
305+
4. **Approve**: Approve the pull request when you're satisfied with the changes.
306+
5. **Merge**: Merge the pull request when you're ready to deploy your changes to production.
307+
308+
## Keyboard shortcuts
309+
310+
The visual editor supports all common keyboard shortcuts such as copy, paste, undo, and select all, and the following shortcuts:
311+
312+
| Command | macOS | Windows |
313+
|:--------|:------|:--------|
314+
| **Search files** | <kbd>Cmd</kbd> + <kbd>P</kbd> | <kbd>Control</kbd> + <kbd>P</kbd> |
315+
| **Add link to highlighted text** | <kbd>Cmd</kbd> + <kbd>K</kbd> | <kbd>Control</kbd> + <kbd>K</kbd> |
316+
| **Add line break** | <kbd>Cmd</kbd> + <kbd>Enter</kbd> | <kbd>Control</kbd> + <kbd>Enter</kbd> |
317+
| **Bold** | <kbd>Cmd</kbd> + <kbd>B</kbd> | <kbd>Control</kbd> + <kbd>B</kbd> |
318+
| **Italic** | <kbd>Cmd</kbd> + <kbd>I</kbd> | <kbd>Control</kbd> + <kbd>I</kbd> |
319+
| **Underline** | <kbd>Cmd</kbd> + <kbd>U</kbd> | <kbd>Control</kbd> + <kbd>U</kbd> |
320+
| **Strikethrough** | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd> |
321+
| **Code** | <kbd>Cmd</kbd> + <kbd>E</kbd> | <kbd>Control</kbd> + <kbd>E</kbd> |
322+
| **Normal text** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> |
323+
| **Heading 1** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> |
324+
| **Heading 2** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> |
325+
| **Heading 3** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> |
326+
| **Heading 4** | <kbd>Cmd</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> |
327+
| **Ordered list** | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> |
328+
| **Unordered list** | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd> |
329+
| **Blockquote** | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd> |
330+
| **Subscript** | <kbd>Cmd</kbd> + <kbd>,</kbd> | <kbd>Control</kbd> + <kbd>,</kbd> |
331+
| **Superscript** | <kbd>Cmd</kbd> + <kbd>.</kbd> | <kbd>Control</kbd> + <kbd>.</kbd> |
332+
333+
## Troubleshooting
334+
335+
Find solutions to common issues you might encounter while using the visual editor.
336+
337+
<AccordionGroup>
338+
<Accordion title="Changes not appearing after publishing">
339+
**Possible causes:**
340+
- Deployment is still in progress
341+
- Browser caching issues
342+
- Build or deployment errors
343+
344+
**Solutions:**
345+
1. Check deployment status in your dashboard.
346+
2. Hard refresh your browser (<kbd>Ctrl</kbd> + <kbd>F5</kbd> or <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd>)
347+
3. Clear your browser cache.
348+
</Accordion>
349+
350+
<Accordion title="Permission errors when publishing">
351+
**Possible causes:**
352+
- Insufficient permissions to the Git repository
353+
- Authentication issues with your Git provider
354+
355+
**Solutions:**
356+
1. Verify you have correct access to the repository.
357+
2. Check if your Git integration is properly configured.
358+
3. Review the [Editor Permissions](/dashboard/permissions) documentation.
359+
</Accordion>
360+
<Accordion title="Editor loading issues">
361+
**Possible causes:**
362+
- Network connectivity problems
363+
- Large documentation repositories
364+
365+
**Solutions:**
366+
1. Check your internet connection.
367+
2. Refresh the page.
368+
3. Contact support if the issue persists.
369+
</Accordion>
370+
<Accordion title="Files not loading or showing errors">
371+
**Possible causes:**
372+
- Invalid MDX syntax in files
373+
- Missing or corrupted files
374+
- Large file sizes causing timeouts
375+
376+
**Solutions:**
377+
1. Check the file syntax for MDX formatting errors
378+
2. Verify the file exists in your repository.
379+
</Accordion>
380+
</AccordionGroup>
381+
382+
## Next steps
383+
384+
- Learn fundamental [Git concepts](/guides/git-concepts)
385+
- Learn best practices for collaborating with [branches](/guides/branches)

0 commit comments

Comments
 (0)