Version control for blogs with static site generators and markdown

MailSlurp publishes its blog and documentation using Markdown files and Astro static pages. This allows for version-controlled content, but it also means that new articles are added through a git flow that is unfamiliar to many writers.

In order to allow content editors to more easily manage MailSlurp marketing and documentation content, 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 Astro

We use static Astro pages for the MailSlurp blog about email and SMS testing. To integrate Decap we can include a static HTML 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 a small Astro route or a dedicated React island.