Comparison of Markdown CMS with version control
Flat file CMS systems compared with git pull requests for static site generator frameworks.
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.
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
Tina is a CMS with version control. It's open source.
- Focus on many static site generators
- Focus on Vercel hosting and Github
- Pushes paid version of tina cloud
2. Decap CMS
- Static site deployment
- Good open source contributions
- Good docs
- Bitbucket support is strong
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
<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>
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
For more control we could instead render the config and admin page using NextJS pages in React.