Self-hosting the markdown editor our engineers already liked

At Pathao, engineers liked writing in a hosted collaborative markdown editor. You open a note, write markdown, share it, and people edit it together in real time.

I wanted to keep all of that and change two things: where it ran and how people signed in.

Why not just ban it

The usual answer to a tool you want to move off is a policy. That rarely works. People used the editor because it was the fastest way to write something down with their team. Take it away without a replacement and the docs move somewhere worse, or stop being written.

So the tool was right. What I wanted to change was the hosting and the sign-in.

The demo

CodiMD is an open-source collaborative markdown editor. Same editing experience, same real-time collaboration, and you can run it yourself.

I set one up and showed it to our CTO. Two points made the case:

• It runs on our own infrastructure. We decide where the notes live.
• It uses the company sign-in everyone already had. No new passwords.

For engineers, nothing changed except the URL.

Adoption

We gave it a short internal name so nobody had to learn a new word.

People started using it, and then everyone in the company was using it. A policy did not drive that. It was the same editor they already liked, with the login they already had.

What I took from it

• Keep the tool, move where it runs. People liked the editor. Changing it would have been a fight. Changing only the hosting was easy.
• Make the safe path the easy path. Company sign-in meant the controlled option was also the one-click option. Nobody had to be told twice.
• A short demo beats a long proposal. Showing the CTO a working instance settled it faster than any document would have.
• Name it. A short name made it feel like our tool and not an IT mandate.

If your team loves a hosted tool, look for the open-source version and run it yourself. Add your single sign-on, keep the same editor, and the move mostly happens on its own.