HN Explorer

Ask HN: Best headless CMS for a developer portal

5 points by datavirtue ↗ HN
I haven't really worked with a CMS since peak WordPress ten-plus years ago. Coming back to this and needing to create a developer portal to document complex API integrations for our clients I am looking for an open-source headless CMS that isn't going to make me pull my hair out. I want to self-host it as I have AWS and Azure available to me at work. Any suggestions for a modern CMS that you enjoyed using?

11 comments

[ 3.6 ms ] story [ 36.6 ms ] thread
colesantiago
Just use WordPress seriously.

All the other CMS‘s are broken and don’t work properly when you upgrade them. I remember Strapi having this issue and most people I talked to would never use Strapi again.

With Wordpress you can easily transfer it to somebody else who knows WordPress and not some immature esoteric CMS system, nobody but the original developer who left the project knows about.

It’s one thing that a system is open source and it’s another if a lot of people knows about that system.

datavirtue
But but...it's not headless. :)

Thanks for the reply.

sneek_
Check out Payload - fully OSS, modeled after the … few good parts of WP

https://payloadcms.com

I built it because I was in the same situation as you.

colesantiago
Looking at the upgrade story it already looks like a nightmare that might make the OP pull their hair out.

Wordpress is a single upgrade button on the CMS, no terminal necessary or needed.

sneek_
WP made me want to pull my hair out
[deleted]
(comment deleted)
datavirtue
Thanks, this looks promising. Upgrades, if problematic as some have mentioned, are not really a concern for me. That's on the next poor fool. I just need to get something out the door to score a bonus.
datavirtue
Have to say, I just wasted two hours trying to get this running...again.

The first time I went through the tutorial I had it up and running in less than five minutes (Windows 11, node 22). A while later I tried the same thing on two work laptops: a M1 and another Windows 11 machine.

It fails complaining that cross-env isn't found. Was not able to find a resolution after hours of trying.

[deleted]
(comment deleted)
datavirtue
Eventually realized that a dependency was unavailable and I had to provide a mirror for it. Really caught me off guard. Payload CMS is looking really clean and solid. I have it deployed successfully to an Azure App Service via BitBucket, leveraging Cosmos.
solardev
(Disclaimer: I work for a headless CMS, but not an open source or self hostable one)

If you're primarily writing docs, have you considered a system for that (like Docusaurus) or a simple MDX (Markdown with JSX) system like Astro or Grav CMS?

The proper headless CMSes are good for managing complex schemas and relationships in a GUI. But if you're primarily documenting code and APIs, IMO being able to write freeform and easily add example snippets and maybe actually workable examples would be nice.

You can also make a pretty good headless CMS off WordPress by using Advanced Custom Fields. However, that was recently taken over by Automattic and part of their war against WPEngine. I'd be afraid of using it.