Comparison of Markdown CMS with version control

Flat file CMS systems compared with git pull requests for static site generator frameworks.

  • Table of contents

MailSlurp publishes its blog and documentation using Markdown files and static site generators like NextJs and Docusaurus. This allows for the version control of content but means that new articles must be added using a git flow that is unfamiliar to most writers.

In order to allow content editors to more easily manage the content on a static site like mailslurp.com and docs.mailslurp.com we explored the latest open source options in markdown content management systems.

What is our setup?

We have a content directory filled with post.md type files containing markdown and frontmatter. During a build step in CI/CD the posts are rendered as HTML. New content must be added via a git pull request.

New requirements

We want a CMS that is:

  • open source, self-hosted
  • deployable on kubernetes or as static site
  • secure and supports SSO login
  • has draft post function
  • can create pull requests and branches
  • has media upload support
  • has good documentation

Markdown CMSs compared

1. Tina.io

Tina is a CMS with version control. It's open source.

Pros

  • Focus on many static site generators

Cons

  • Focus on Vercel hosting and Github
  • Documentation
  • Pushes paid version of tina cloud

2. Decap CMS

Formerly Netlify CMS, Decap is a popular offering with 16k GitHub stars at time of writing.

Pros

  • Static site deployment
  • Good open source contributions
  • Good docs
  • Bitbucket support is strong

Cons

  • ?

Integrated Decap CMS with NextJS

We use NextJs for our blog about email testing at MailSlurp. To integrate decap we can simply include a static HMTL file at /public/admin/index.html :

<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
</head>
<body>
<!-- Include the script that builds the page and powers Netlify CMS -->
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
</body>
</html>

Configuration

To configure the connection between content and Bitbucket we include a config.yml file as a sibling to index at /public/admin/config.yml. This might look like this:

backend:
  name: bitbucket
  repo: mailslurp-org/landing
media_folder: public/media
media_library:
  name: cloudinary

Dynamic approach

For more control we could instead render the config and admin page using NextJS pages in React.