Headless CMS options (and Readme.io)
I'm giving an API documentation workshop in Mountain View, California on August 30, 2019. If you're interested, you can register on EventBrite.
Rounding out the publishing tool options, there is a class of developer doc tools that provide online GUIs for authoring and publishing, but they still store your content as flat files in repositories such as GitHub and Bitbucket. In other words, they provide a WordPress.com-like experience for your content (giving you a user interface to browse your posts, pages, layouts, and other content) but allow your content to live in plain text files in version control repositories. This type of tool is called a “headless CMS” because they are missing the head (database) as the source for your content.
List of headless CMS options
Just as we have staticgen.com that lists common static site generators, there’s a similar index of headless content management systems, this one arranged in alphabetical order (rather than ranked by popularity).
Headless CMSs often combine both the authoring and the hosting/deployment in the same tool. Updates you make are built automatically on the platform. But unlike WordPress, the solution does not involve storing your doc content in a database and dynamically retrieving that content from the database when readers visit your page. Many times you can store your content on GitHub, and the headless CMS will read/pull it in seamlessly. (The platform probably will contain a database of some kind for your profile and other CMS features, but your content is not stored and retrieved there.)
Forestry.io is similar to CloudCannon in that it offers online hosting for Jekyll projects, but it also provides hosting for Hugo and Git. Forestry’s emphasis is on providing an online CMS interface for static site generators. The CMS interface gives you a WordPress-like GUI for seeing and managing your content.
The idea behind the CMS interface is that most static site generators ostracize less technical users by forcing them into the code. (For example, when I write a post in Jekyll, usually others who look over my shoulder think I’m actually programming, even though I’m just writing posts in Markdown.) The CMS removes this by making the experience much more user-friendly to non-technical people while also still leveraging the openness and flexibility of the static site generator platform.
CloudCannon could also be considered a headless CMS, but I chose to categorize it in the hosting and deployment solutions because it has less of an emphasis on authoring in its GUI. Forestry.io (unlike CloudCannon) also offers an on-premise enterprise installation so you can host and manage the entire platform behind your company’s firewall.
Netlify CMS is similar to Forestry in its offering of a content management system for static site generators. But rather than limiting the static site generators you can use, it provides a more open platform wrapper (built with React but using Git to manage the content) that integrates with any static site generator.
One of Netlify CMS’s key advantages is in simplifying the content development experience for less technical users. But you can also standardize your authoring through the interface. Netlify CMS lets you map the custom fields in your theme to a GUI template, as shown in the image below. These custom fields reduce the chance that authors might use the wrong frontmatter tag in their pages (for example,
introBlurb). Here’s a sample interface:
Your content source can be stored in GitHub, GitLab, or BitBucket. Netlify CMS also integrates with Netlify, which is a popular hosting and deployment service for static site projects.
Readme.io is an online CMS for docs that offers one of the most robust, full-featured interfaces for developer docs available. Readme.io isn’t a headless CMS, meaning you don’t just point to your GitHub repo to pull in the content. Instead, I believe Readme.io stores content in a database (though this detail isn’t mentioned on their site). So strictly speaking, I probably shouldn’t include Readme.io here, but I didn’t know where else to describe it, and the CMS-like GUI makes it the most similar to the headless CMS.
Readme.io’s emphasis is on providing an interface that helps you more easily write documentation based on best practices and designs. Readme.io provides various wizard-like screens to move you through documentation processes, prompting you with forms to complete. For example:
Most importantly, Readme.io includes specific features for displaying API documentation content, which puts it into a class of its own. Although you can add your API information manually, you can also import an OpenAPI specification file. You can experiment by choosing one from the OpenAPI examples, such as this one. Readme.io’s integration of OpenAPI along with other doc content helps integrate outputs that are often separated. (This fragmentation is a problem I explore later in Integrating Swagger UI with the rest of your docs.)
Overall, Readme.io provides a robust GUI for creating API documentation in a way that is more extensive and well-designed than virtually any other platform available. The output includes an interactive, try-it-out experience with endpoints:
The experience is similar to Swagger in that the response appears directly in the documentation. This API Explorer gives you a sense of the data returned by the API.
There are some challenges with Readme.io. It isn’t free, so you’ll need licenses per author. Additionally, there isn’t any content re-use functionality (currently), so if you have multiple outputs for your documentation that you’re single sourcing, Readme.io may not be for you. Finally, if you want to customize your own design or implement a feature not supported, you can’t just hack the code (though you can adjust the stylesheet). Overall, with a hosted solution like Readme.io, you’re stuck within the platform’s constraints.
Even so, the output is sharp, and the talent behind this site is top-notch. The platform is continuously growing with new features, and there are many high-profile companies with their docs on Readme. If you consider how much time it takes to build and deploy your own doc solution, going with a site like Readme.io will save you a lot of time. It will let you focus on your content while also adhering to best practices with site design.
Here are a few sample API doc sites built with Readme.io:
Which tool should you use? I provide some more concrete recommendations in Which tool to choose for API docs – my recommendations.
89/121 pages complete. Only 32 more pages to go.
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.