Hack: how we moved Pathao docs off public HackMD and behind our firewall

Around 2023, Pathao engineers wrote docs on HackMD. It is a good tool. You open a note, write markdown, share the link, and people edit it together in real time.

That was the problem. It was too easy to share.

What was wrong

Internal docs and API documentation lived on a public SaaS. Notes were shared by link, and those links worked from anywhere on the internet. Nobody was doing anything careless on purpose. That is just how the tool works.

But the notes held things that should never leave a company:

• API docs for internal services: endpoints, payloads, how services talked to each other.
• Internal documentation about systems, processes and decisions.

Anyone who got hold of a link could read it. We had no real control over who saw what, and no way to know.

Why not just ban it

The usual fix is a policy: "do not put internal docs on HackMD". That never works. People used HackMD because it was the fastest way to write something down with their team. Take it away without a replacement and the docs move to somewhere worse, or stop being written.

The tool was right. Where it ran was wrong.

The demo

CodiMD is the open-source version of HackMD. Same editor, same markdown, same real-time collaboration. You can run it on your own servers.

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

• It runs inside our network. Docs stay behind the company firewall.
• It works with Google login. Everyone already had a company Google account. No new passwords, and only people at Pathao can sign in.

For engineers, nothing changed except the URL.

Hack

We called it Hack. A short name, close enough to HackMD that nobody had to learn a new word.

People started using it, and then everyone in the company was using it. Not because of a policy, but because it was the same tool they already liked, with their company login.

Where it ended up

All of Pathao's internal data and API docs moved inside the company firewall. Notes that used to be one leaked link away from the open internet now need a Pathao Google account to open.

What I took from it

• Keep the tool, move where it runs. People liked HackMD. Changing the editor would have been a fight. Changing only the hosting was not.
• Make the safe path the easy path. Google login meant the secure 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 with Google sign-in settled it faster than any document about risk would have.
• Name it. "Hack" made it feel like our tool, not an IT mandate.

If your team writes internal docs on a public SaaS because it is convenient, look for the open-source version and run it yourself. Add your company's single sign-on, keep the same editor, and the move mostly happens on its own.