Guides #SAAS

All content in this site is actually written and managed in, then published using This is a very new way to think about documentation. But, if you’re considering using a CMS like Contentful or Wordpress to write your articles, why not Notion? Notion has by far the most user-friendly interface. It supports team collaboration. The finished site looks good.
You can even host it on a /docs subdirectory in your own Next.JS or CloudFlare-hosted app!

Markdown files #self-hosted

The standard way to make technical documentation websites is with an open source codebase, of which there are several to choose from. The articles are kept in the codebase. Each article is a markdown file (text file). To enable keyword search, a script can be installed that searches the filesystem. The newer way to do it is to use MDX (keep reading below solutions). But classic markdown is simpler. Many open source projects have excellent documentation sites built and served in this very simple way. NPM is a great example. Main benefit is Git version control.
Image without caption

MDX files #self-hosted

Powerful new tech that is taking over how technical/engineering documentation sites are made. A front-end technology. You manage your pages/articles as files in the codebase. Like MarkDown.
It is Markdown that fully supports React JSX. It’s a combination. Very cool. Used a lot by Vercel and popular with front-end React devs. is a good example.
Because of this powerful functionality, this is a great solution when you need your documentation site to also be your marketing site. Like when you‘re marketing to engineers.
It’s all DIY. Easy copy/paste from open source repositories. Nextra + Algolia = search.
Image without caption

Mintlify #SAAS

There’s a service for that!
Very promising. It’s a custom development platform. Manage your docs in your own Github repo. They give you some useful components to use. This probably uses MDX/React. I haven’t tried it yet. Looking forward to trying it soon. This screenshot is one from their showcase of customer sites:
Image without caption

Astro #self-hosted

Open source self-hosted framework from:
🍀 Makes excellent looking guides and navigation! Same as used by many tech companies.
Image without caption

Docusaurus #self-hosted

Open-source by Facebook. Self-hosted. Similar to Astro.
Image without caption

Confluence #SAAS

By Atlassian, makers of Jira. Also good documentation. Very popular with enterprise companies.
It’s NOT meant for a public-facing SEO site, but for internal documentation and knowledge base.
But it is possible to publish your Confluence space as a “Help & Support” public website if you use this plugin:
Image without caption
✅ Publishes the best looking and most performant documentation website. Easy to manage.
✅ It’s the best of both worlds: SAAS and self-hosted. The content is stored in your own Github repository in markdown format. You control your own data in a standard format that you can take with you to any other platform! But, though you host your content, you may still edit it by logging in to their app, using their intuitive and feature rich WYSIWYG text editor.
🛑 Unfortunately, they redesign their admin/editing app every few years, and each time it gets slower and more awkward to use. At this point, Confluence has better UX. It’s sad. It used to be open source, and the UI was so fast and easy to use. That was 10 years ago. Now it still gets the job done, and actually has more features (collaborate with team members, manage permissions) but the user experience has gotten worse as a result of them adding more features.
Image without caption #self-hosted

It’s open-source. Here’s the repository. Great landing pages for documentation categories. This uses markdown files to store the content, and GIT to manage collaboration/history.
Image without caption
Image without caption

MkDocs #self-hosted

End result looks like a full website rather than the more standard looking docs you usually see. But the search results is more sophisticated than average.
Image without caption

Radash #self-hosted

Built with NextJS. Clone it here. Great layout and navigation, but the search is weak, only searches and shows titles. I would love to make a version of this with a full content search, that shows results sorted by relevance, first matching titles then descriptions.
Image without caption
Great UI and typography. You will enjoy writing documentation. People will enjoy reading it. There are many great features like re-usable content blocks, so you can show the same content in multiple pages without having to maintain duplicate content. lets you collaborate on content with multiple team members. Unfortunately, publishing a notion site results in a poor user experience. No sidebar navigation on the published site. It’s slow to load. Bad SEO. lets you compile and publish your Notion space as a static website with SEO, custom logo, custom CSS and HTML, and other added features. It lets you add a navigation sidebar. But unfortunately for now, you’ll have to define all the links manually, and update them when they change. It can’t auto-generate to reproduce the sidebar just like in your Notion editor. Also, the search doesn’t seem to function at all, but this may be fixed by the time you read this. If you don’t mind building the sidebar links manually, this is worth a try.
Image without caption
Image without caption

Cosmic #self-hosted

Open source like Astro. Doesn’t seem as advanced as others, but it’s clean. #self-hosted

This is just a script created and used by Stripe to convert markdown into HTML. There are many other good scripts out there. I like npm markdown-it combined with html-react-parser. It’s better because it can be set up to inject React components into a string of HTML. Like MDX, but not as capable.
Here’s their starter project. It’s not a complete solution. No search. But it’s very simple and lightweight.