Visual Editor
Edit documentation content directly in the browser with HolyDocs' visual and code editors.
Overview
The HolyDocs editor lets you write and edit documentation without leaving your browser. It offers two modes — a rich-text Visual editor powered by TipTap and a syntax-highlighted Code editor powered by CodeMirror — so you can work however you prefer.
Access the editor from the Editor item in your project sidebar.
Editor Modes
The editor provides two distinct editing experiences. Switch between them using the mode toggle (a segmented pill control) in the editor toolbar.
The Visual editor presents a WYSIWYG editing surface similar to Notion or Google Docs. Content is rendered in real time as styled HTML while you type.
Formatting toolbar features:
- Text styles — Headings (H1–H6), paragraph, bold, italic, strikethrough, inline code
- Block elements — Blockquotes, horizontal rules, callout boxes
- Lists — Ordered, unordered, and task/checklist lists
- Links — Insert and edit hyperlinks with URL validation
- Images — Upload from your device, paste from clipboard, or reference a URL
- Tables — Insert tables with add/remove row and column controls
- Code blocks — Syntax-highlighted fenced code blocks with language selector
- Components — Insert HolyDocs components (Callout, Card, Tabs, Steps, Accordion) from a slash command menu
Type / on an empty line to open the slash command menu. Search for any block type or component by name — for example, /callout or /table.
The Code editor displays the raw MDX source in a CodeMirror instance with full syntax support.
Code editor features:
- MDX/Markdown syntax highlighting
- JSX component highlighting within MDX
- Line numbers and active line highlighting
- Bracket matching and auto-closing
- Find and replace (Cmd+F / Ctrl+F)
- Code folding for large sections
- Multiple cursor support (Cmd+D / Ctrl+D to select next occurrence)
- Minimap for navigating long files
Switching Modes
Click the Visual / Code segmented toggle in the top toolbar to switch. Your content is preserved when switching:
- Visual to Code — The HTML content is converted to clean Markdown using turndown. Component markup is preserved as JSX.
- Code to Visual — The MDX source is parsed and rendered into the rich-text editor. Invalid MDX syntax is highlighted with an inline error banner rather than being silently dropped.
If your MDX contains advanced JSX expressions or custom components that the Visual editor cannot render, those sections appear as read-only code blocks in Visual mode. Switch to Code mode for full control over complex markup.
File Browser
The left panel of the editor displays a file tree of all pages in your documentation project. Pages are organized according to your docs.json navigation structure.
File Browser Features
- Search — Type in the filter field at the top to filter pages by name or path
- Create page — Click the + button to create a new MDX file. Choose a path and an optional title; HolyDocs scaffolds the frontmatter for you
- Rename — Right-click a file to rename it. HolyDocs automatically updates navigation references in
docs.json - Delete — Right-click and select Delete to remove a page. A confirmation dialog prevents accidental deletions
- Drag and drop — Reorder pages by dragging them in the file tree. This updates the navigation order in
docs.json
The file browser shows pages from your Git repository. New pages you create through the editor are staged locally until you save and deploy.
Creating New Pages
Click the + button
In the file browser panel, click the + icon or use the shortcut Cmd+N / Ctrl+N.
Set the file path
Enter a path relative to your docs root, for example guides/authentication.mdx. Nested directories are created automatically.
Add frontmatter
HolyDocs pre-fills the frontmatter with a title and description field. Edit these before writing content.
Write content
Start typing in Visual or Code mode. Your changes are saved to the local content buffer automatically.
Content Buffer
The editor uses a local content buffer to store your in-progress changes. This means:
- Unsaved changes persist across page reloads — Close the tab and come back; your edits are still there
- Per-file tracking — Each page has its own independent buffer. You can edit multiple pages and save them together or individually
- Diff indicator — Files with unsaved changes display a dot indicator in the file browser
- Discard changes — Right-click a modified file and select Discard changes to revert to the last deployed version
The content buffer is stored in your browser's IndexedDB. Clearing browser data will discard all unsaved changes. Save and deploy regularly to avoid losing work.
Saving and Deploying
When you are ready to publish your changes:
Save your changes
Press Cmd+S / Ctrl+S or click the Save button. This writes your content to the Git repository (via a commit on your configured branch).
Review the commit
A dialog shows the list of changed files with a diff preview. Add an optional commit message or use the auto-generated one.
Deploy
Saving automatically triggers a deployment. You can monitor the build status from the deployment badge in the editor toolbar or from the Deployments page.
Save Options
| Action | Shortcut | Behavior |
|---|---|---|
| Save | Cmd+S / Ctrl+S | Commit changes and trigger deployment |
| Save draft | Cmd+Shift+S / Ctrl+Shift+S | Commit to a draft branch without deploying to production |
| Save all | Cmd+Alt+S / Ctrl+Alt+S | Save all modified files in a single commit |
OpenAPI Pages
Pages generated from an OpenAPI specification are displayed as read-only in the editor. Instead of an editable content area, you see:
- Endpoint info panel — Method, path, summary, and description
- Parameters — Path, query, and header parameters with types
- Request body — Schema preview with example payloads
- Responses — Status codes with response schemas
To modify OpenAPI-generated pages, update your OpenAPI specification file and redeploy. The spec URL is configured in Settings > API.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| Cmd+S / Ctrl+S | Save current file |
| Cmd+N / Ctrl+N | Create new page |
| Cmd+P / Ctrl+P | Quick file search (fuzzy match) |
| Cmd+F / Ctrl+F | Find in current file (Code mode) |
| Cmd+Shift+F / Ctrl+Shift+F | Find across all files |
| Cmd+B / Ctrl+B | Toggle bold (Visual mode) |
| Cmd+I / Ctrl+I | Toggle italic (Visual mode) |
| Cmd+E / Ctrl+E | Toggle inline code (Visual mode) |
| Cmd+K / Ctrl+K | Insert link (Visual mode) |
| Cmd+Shift+M / Ctrl+Shift+M | Toggle between Visual and Code mode |
| Cmd+Z / Ctrl+Z | Undo |
| Cmd+Shift+Z / Ctrl+Shift+Z | Redo |
Tips for an Efficient Workflow
In Visual mode, type / on an empty line to open the component picker. This is faster than using the toolbar, especially for inserting callouts, code blocks, and steps.
Open your documentation site in a second browser tab. After saving and deploying, the preview updates within seconds. Use split-screen mode for a side-by-side writing experience.
For find-and-replace across a page, switch to Code mode and use Cmd+H / Ctrl+H. This is faster than editing each instance individually in Visual mode.
When rewriting multiple pages, use Save draft to commit to a separate branch. This lets you preview changes without affecting production until you merge.