The Visual MDX Editor: Write Beautiful Docs Without Ever Touching Git

Here's a scenario that plays out in thousands of companies every day.

Your product team ships a new feature on Tuesday. On Wednesday, someone in support notices the docs are wrong—a small thing, maybe a parameter name or an outdated screenshot. They ping the engineer who wrote the feature. The engineer is heads-down on the next sprint. The fix gets added to a Notion backlog.

Three weeks later, the engineer finally has time. They clone the docs repo. They open their code editor. They edit an MDX file. They push a branch. They open a pull request. Someone reviews it. It gets merged. The CI pipeline runs for four minutes. The docs deploy.

Total time to fix a typo: three weeks and about twenty-seven minutes of actual work.

This is the reality of "docs-as-code" workflows, and it's one of the most quietly frustrating experiences in software development. The tooling is technically correct. It's also a productivity disaster for teams that aren't full-time documentation engineers.

The fix isn't to abandon MDX or version control. The fix is to stop forcing every tiny change through a git workflow. That's what Dokly's visual MDX editor is for.

The Problem with Docs-as-Code#

Docs-as-code emerged for good reasons. Keeping documentation in your repository alongside your code means:

• Docs are versioned with the code they describe
• Pull requests can update docs and code together
• Engineers can make changes in their existing workflow
• You get the same review rigor you apply to code

These are real benefits. For some teams, on some projects, they're the right tradeoff.

But the downsides have been quietly accumulating:

The tooling overhead is substantial#

You need a static site generator. You need a CI pipeline. You need preview deployments for PRs. You need a custom theme (or a starter kit you've heavily modified). You need someone on the team who understands how all of this fits together when it inevitably breaks.

We've watched teams spend three weeks setting up Docusaurus or a Next.js docs site before writing a single page of actual documentation.

Non-engineers can't contribute#

Your customer success team knows what documentation is missing. Your product manager spotted the error. Your new hire has the fresh perspective. But if the workflow requires cloning a repo and opening a code editor, none of them will contribute.

You've just excluded the people with the most relevant knowledge from writing the docs.

Small fixes become big ceremonies#

Fixing a broken link, updating a price, renaming a feature—these should take thirty seconds. In a docs-as-code workflow, they take thirty minutes when you account for the branch, the PR, the review, the CI run, and the deploy.

Multiply that by every small fix across the year, and you're spending a non-trivial amount of engineering time on documentation plumbing instead of writing.

Previewing is awkward#

Most docs-as-code setups render locally with a dev server, or you push to a preview branch and wait for Vercel or Netlify to build it. Either way, you're one step removed from "type, see, adjust." The feedback loop is broken.

MDX is powerful but fragile#

MDX—Markdown with JSX components—is a brilliant format for documentation. You can embed interactive React components alongside your prose, which makes docs richer than plain Markdown ever could. But MDX also breaks in subtle ways. A mismatched <Tab> tag. An unescaped angle bracket. A component prop in the wrong format. The build fails, and now someone is debugging their docs instead of writing them.

What a Visual MDX Editor Actually Does#

When we say "visual MDX editor," we don't mean another WYSIWYG that hides the underlying format. We mean an editor that understands MDX natively, renders it live, and lets you work in whichever layer makes sense for the task.

Dokly's editor works like this:

Two-pane, live-updating workflow#

On one side, you write. On the other side, you see exactly what your docs will look like when published. Every keystroke updates the preview. There's no build step, no deploy, no "wait, let me push and refresh."

This matters more than it sounds. The feedback loop between "I wrote something" and "I can see if it works" collapses from minutes to zero. You catch formatting mistakes immediately. You adjust spacing and structure as you go. Writing stops being a debug cycle and starts being writing again.

Rich blocks without leaving the document#

Want to add a callout? A code block with syntax highlighting? A tabbed interface for showing multiple language examples? A comparison table? A collapsible accordion?

In a traditional MDX setup, you'd remember the component name, remember the prop syntax, look up the correct usage, and hope you typed it right.

In the visual editor, you use a slash command (/callout, /tabs, /code) or pick from a component menu. The block inserts correctly. You fill in the content. The preview shows the result instantly.

You never need to remember whether it's <Tabs> or <TabGroup> or what props the callout component accepts.

Raw MDX access when you want it#

Here's the critical part: visual editing doesn't mean giving up control. At any point, you can switch to raw MDX view and edit the source directly. You can paste in MDX from another source. You can hand-tune the component usage.

For most writing, the visual interface is faster. For complex cases—nested components, custom props, unusual layouts—the raw view is right there.

It's not a lossy conversion. What you see in the visual editor is the same MDX that gets published. No intermediate format, no "export" step that might scramble your structure.

Instant publishing#

When you're ready to publish, you click publish. The page is live in seconds.

There's no build queue. No CI pipeline. No "your deploy is #3 in the queue, estimated time 4 minutes." The moment you click, the page is updated on your docs site.

For urgent fixes—a broken link during a launch, a typo in a pricing announcement, a correction after a customer complaint—this is the difference between a 30-second fix and a 30-minute fire drill.

But What About Version Control?#

This is the most common objection to visual editors, and it's a fair one. How do you review changes? How do you roll back? How do you collaborate without overwriting each other's work?

Dokly handles this without making you run git commands:

Revision history for every page#

Every page maintains a complete revision history. You can see who changed what, when, and view the exact diff between versions. If a change introduced a problem, you can revert to any previous version with one click.

This is the capability git gives you, with none of the workflow overhead.

Draft and publish states#

Every page has a draft state separate from its published state. You can write, edit, and iterate without your changes going live. When you're ready, you publish. Until then, your draft is safe, versioned, and invisible to readers.

This means you can work on major rewrites for days without worrying about a half-finished page being visible to users.

Team collaboration with proper conflict handling#

When multiple people edit the same page, the editor handles it gracefully. You see who else is active. Changes merge in real time, not via PRs.

For teams that want formal review workflows, those are available on the Team plan. But for most changes—the daily flow of updates, corrections, and additions—you just write and publish.

Git sync, if you want it#

For teams that have specific reasons to keep docs in git (monorepo requirements, engineering review culture, contractual obligations), Dokly supports bi-directional git sync on the Team plan. Edit in the visual editor, and commits are pushed to your repo. Edit in your repo, and changes pull into the editor.

You don't have to choose. You get both.

Who Actually Benefits from This#

Solo developers and indie hackers#

You're the engineer, the designer, the marketer, and the docs writer. You do not have time to maintain a separate Docusaurus build. You need to be able to update docs during a demo call and have the fix live before the call ends.

Visual editing is the difference between documentation you keep up to date and documentation you wrote once in 2024 and haven't touched since.

Small startup teams#

Your engineers are busy. Your product team and customer success folks know what documentation is needed, but can't contribute if the workflow is git-based. A visual editor means your non-engineers can write docs—reviewed by engineers if needed—without blocking on engineering time.

This shifts documentation from "thing engineers do in their spare time" to "thing the whole team contributes to."

Open source maintainers#

Your contributors are spread across the world, with varying levels of git comfort. A first-time contributor wants to fix a typo in your README's linked docs. If the workflow is "fork, clone, branch, commit, PR," they won't do it. If the workflow is "click edit, fix the typo, submit," they will.

Visual editing dramatically lowers the contribution barrier for documentation.

Developer tool companies#

You ship frequently. Your API changes. Your examples need to be kept in sync with the latest SDK version. The faster your docs team can iterate, the more accurate your docs stay. Every hour saved on docs plumbing is an hour spent on content.

Real-World Workflow Examples#

Example 1: The pricing page update#

Your pricing changed. You need to update the docs.

Docs-as-code workflow:

1. Clone the docs repo
2. Open the pricing MDX file
3. Update three references across four files
4. Commit, push, open PR
5. Wait for review
6. Merge
7. Wait for CI
8. Deploy

Total time: 45 minutes if everyone's fast.

Dokly visual editor workflow:

1. Open each page
2. Update the price
3. Click publish

Total time: 3 minutes.

Example 2: The new feature launch#

You're shipping a new feature tomorrow and need a new docs page.

Docs-as-code workflow:

1. Clone the docs repo
2. Create a new file with the right front-matter
3. Add it to the sidebar configuration
4. Write the content, previewing via dev server
5. Realize a component isn't importing correctly, debug for 20 minutes
6. Commit, PR, review, merge, deploy

Total time: half a day, sometimes more.

Dokly visual editor workflow:

1. Click "new page" in the sidebar
2. Write the content, seeing the preview as you type
3. Use slash commands to insert callouts, code blocks, tabs
4. Click publish

Total time: however long it takes to write the content. No tooling tax.

Example 3: The urgent typo#

A customer just tweeted about a typo on your landing docs page.

Docs-as-code workflow: 30 minutes including the full cycle.

Dokly visual editor workflow: Open page, fix typo, publish. Done in under a minute, respond to the tweet with a thank-you.

What About Developers Who Prefer Git?#

Some developers genuinely prefer editing docs in their IDE. That's fine. You have options:

1. Use Git Sync (Team plan) to keep your docs in a repo while still letting non-engineers use the visual editor
2. Use raw MDX view within the editor to edit with a code-like interface
3. Export your docs at any time to a git repository

The visual editor doesn't force a workflow on you. It removes the requirement that every change must go through git, which is a very different thing from eliminating git entirely.

The Philosophical Point#

There's a deeper issue underneath all of this.

For the past decade, developer tools have optimized for developer sophistication. Complex setup was a feature, not a bug—it signaled seriousness. If your docs site required a custom Webpack config, that meant you were a real company.

That era is ending. The new generation of tools—Linear, Vercel, Framer, Arc—proves that simplicity and power aren't opposites. A tool can be simple to use and still produce professional output.

Documentation has been one of the last holdouts. "Real" docs still felt like they needed Docusaurus, a custom theme, and a CI pipeline. That's wrong. Real docs need to be written, maintained, and kept in sync with your product. Whatever workflow gets that result is the right workflow for your team.

For many teams, the right workflow is visual editing with optional git sync. For some, it's still git-first. Dokly supports both. Most platforms support only one.

Try It#

The fastest way to understand the difference is to use it for ten minutes.

Sign up for Dokly—the free tier includes unlimited pages and the full visual editor. Create a page, add a code block and a callout using slash commands, and publish. You'll have a live, public docs page in under two minutes.

Compare that to how long it took to set up your last docs platform. That difference, multiplied across every update you'll ever make, is what Dokly saves you.

Beautiful docs should not require a week of setup and a custom build pipeline. They should require a blank page and something to say.