Pure markdown is fine until you need decent tables or structured metadata. Docs-in-repo sounds clean on paper, but the minute you need comments, suggestions, inline edits, permissions, and approvals from people who do not live in git all day, you are recreating half of Notion or Google Docs with plugins and glue code.

Then you ask marketing or support to open a PR. That is usually where the markdown honeymoon ends.