Proposal: edit-mode website with live WYSIWYG edition for multiple versions synced with git

[choucavalier]

Context

Currently, it's not possible to edit an mkdocs website, as it's statically generated.

Two possibilities exist:

1. Using a Markdown editor app. Pros: easy to set up, local, works offline. Caveats: that's not going to be fully compatible with mkdocs (which contains many features, and can be highly customised), and therefore not actually WYSIWYG.
2. Run your own version of the website locally. But this requires first editing the Markdown, then re-compiling, refreshing the browser. This is not fluid at all.

To give an example of a totally different experience, let's take the example of Notion, where you can edit everything in live, directly in the doc, and save it. This experience is just great, because people can focus on the content and nothing else.

Description

We could have an edit-mode version of mkdocs, which would make it possible for different users to edit their own version of the doc, in WYSIWYG. Instead of being static, this version of the website would be dynamic. All the doc content would be editable, and live previewed.

Using git, we would be syncing the edit/{user} branches with main (in both directions).

On the website, Bob and Alice can both (1) save their changes (creates a git commit on edit/bob or edit/alice in the background), and (2) fetch the latest version from main.

We could even think of having a collaboration feature, which would allow Alice and Bob to work on the exact same version of the website, see where they are on page, see each other's editions in real-time.

Related links

• Requesting a change

Use Cases

This would be a killer feature. It would combine the power of git versioning, the simplicity of markdown, with an actually amazing user experience. This would allow non-tech people to focus on content creation, actual documentation, removing a lot of the friction that currently exists when writing Markdown-based documentation. This would also expand the reach of this project to projects that are not necessarily ran by tech savvy people, but also other types of content creators.

Visuals

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting! Honestly, this is quite beyond the scope of this project. I agree, that it would be awesome to have something like that, but it wouldn't be just a feature but a whole project or even product of its own. Implementing a full-blown WYSIWYG editor with git integration and everything is a full-time job. There are several WYSIWYG Markdown editors out there, which already tick some of the requirements. We're considering this out-of-scope.

We might follow up on #2110 (live preview) in the future, but currently no ETA.

[squidfunk]

On a side note, CloudCannon claims they have a MkDocs CMS. I'd be very interested in experiences with that.

[cbeauhilton]

@squidfunk here's a bit of experience with CloudCannon:

I'm playing with their offering right now, seems to work well with MkDocs-Material. I had to add a "pip install -r requirements.txt" to the prebuild step to get MkDocs-Material and plugins into the environment, but that was about it. Here's the current preview URL, pretty good: https://fleet-kite.cloudvent.net (original is https://vimbook.org).

As far as configuring the WYSIWYG part, I copied the yml from https://cloudcannon.com/blog/how-to-set-up-wysiwyg-editing-with-mkdocs/ (they have an interactive yml config builder, but it confused me) and it worked without changes.

Our site is a handbook for resident doctors at Vanderbilt, peer-reviewed and updated yearly, so it would be great to have a WYSIWYG option for the writers (all physicians) to edit the site directly (as it is, a couple of us who are comfortable with GitHub receive Word docs and make the updates manually). The main problem with CloudCannon is that it's pretty pricy, $45/mo for a team of 3, $250/mo for a team of 15, $10/head for additions (https://cloudcannon.com/pricing/), which isn't going to cut it for a bootstrapped project with an operating budget of approximately $0 and a few dozen editors. So, the search continues!

DecapCMS (formerly NetlifyCMS) may be another option. I've used that one successfully before with a different backend (Hugo), and it can be free to use. It's built on similar principles to CloudCannon (WYSIWYG that pushes changes to GitHub), but seems that it would take a bit of massaging to integrate with MkDocs. https://decapcms.org/docs/choosing-a-backend/ .

[squidfunk]

Thanks for the very valuable feedback! We're actively considering going down the WYSIWYG route, but please know that it is a pretty big fish to fry. We might start exploring directions in the coming months, but we currently can't put an ETA on it. We'll keep everybody updated in #2110.

[mvtab]

Hello,

first of all, I must say such a feature is simply game-changing. MkDocs Material is already being massively used as is. With a live editor, I think the project would reach amazing heights.

However, I don't really like the idea of making commits to the source repository at every single change of a page, because this would really complicate things. The main problem being: the artifacts must be built after every single edit. This means no matter how much of the source code you change, you will always rebuild the entire project. While this shouldn't be a problem at small projects, at big projects with a lot of contributors it could backfire tragically.
Alongside that, you have performance and efficiency issues, due to the fact that you have to actually connect the Webserver to the git repository, which in turn leads to security concerns and whole other problems.

Of course, you could make the live edits directly on the static website and then just push the changes to the repo (probably the current solution), but maybe the repo isn't available when you push the change, and the changes get propagated to the website but not the source. Of course, you can avoid this too by making sort of a queue, but again, this gets uselessly complicated.

I believe the best solution would be to add a database/redis "feature" to the setup. For example:
The whole internal infrastructure stays the same, but you should have the possibility of telling mkdocs to save every generated static content to an external storage (db/redis, self managed, not part of the setup), and if this option is activated, then the generated static website should simply query the storage for information, instead of having everything hard coded. One could simply save the whole generated page HTMLs into Redis keys for example, and then query them when displaying.

This has the advantages that users can simply continue using the application as is, ignoring the new feature if not interested, and who does use the feature can manage everything as another normal application: you bootstrap the app with some content, but the dynamic content is saved in a storage that you can backup and restore.

While this would cover another critical feature: RBAC, it would allow for more elegant solutions to adding a live editor.
To make this better, one could add an export function to the static website, which would generate markdown content out of all the dynamic content, for example to update the source code once in a while.

And yes, I know this implies a lot of work and there are many variables that might not work, but it would bring a whole lot of great functionality to the application.

[squidfunk]

@mvtab thanks for the feedback! We already have a pretty clear vision of how this should look. We have a lot of work in front of us, but we'll eventually implement this. At first, it'll be a side-by-side editor (Markdown + HTML), but once we managed to build that, the next logical step will be a WYSIWYG editor. One step at a time with a team that small ☺️

[mvtab]

Great, glad to hear you are already working on this. Do you have a roadmap yet?

[squidfunk]

We're working on bigger picture topics in the background right now, including a public roadmap. Please bear with us, we need some more time, as we're a very small team working on this project used by tens of thousands of people.

[valhuber]

Like all, I would love an editor.

I've built a pretty big manual, and my biggest issue is that I cannot visualize the 'outline' when I'm editing a large page. So, a 2-pane editor (outline and existing text) would address that at perhaps less cost.

The context here is that I edit the doc files in vscode. The md preview is helpful, and I also use mkdocs serve (a lot).

Again, great offering, thanks for creating it!