Last Updated: August 17, 2018

Editing Middleman site with Netlify CMS and GitLab

Static site generators are great in its simplicity. But editing content is a challenge for less technically experienced people. Netlify CMS solves it all without needing complex CMS solutions. Keep it simple and accessible for new editors and developers! Unlike “static site” with React frontend talking to GraphQL API, that loads from Wordpress API...

Adding a CMS to Middleman

Follow instructions from Netlify docs. Create an admin directory with an index.html and a config.yml file.

source/
  admin/
    index.html
    config.yml

The index.html isn't important. Copy-paste it from docs. The config.yml is more important. It contains configuration of your CMS.

Connecting a CMS to Gitlab repository

Netlify CMS offers various authentication options. I'll go with Gitlab. The complete configuration highly depends on your site. Here is the example of config.yml.

# auth & repository hosting
backend:
  name: gitlab
  repo: sokolmorasice/web
  branch: master

# images
media_folder: source/public/images/uploads
public_folder: /public/images/uploads

# content types
collections:
  - name: "settings"
    label: "Settings"
    folder: "source/admin/data"
    create: false
    extension: md
    format: yaml-frontmatter
    fields:
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Content", name: "body", widget: "markdown"}

I don't recommend using extension.html.md. It caused weird issues. Use md extension, update sitemap via manipulate_resource_list, so build creates file.html.

Editing content in a CMS

Admin works without any configuration. Run your site with bundle exec middleman and open admin page. But that's not acceptable for external editors who don't know Middleman, ruby etc.

Netlify CMS Expects site hosted at Netlify

Admin at production is little more tricky if your site isn't hosted at Netlify. CMS doesn't work if you are hosting site somewhere else. You might see following error.

Take a look at site_id in Netlify Authorization. It basically expects Netlify site. Yes, there are options for running Auth without Netlify. But I'd like to keep it simple and use Gitlab + Netlify CMS without any extra services.

Admin site hosted at Netlify

Solve it by hosting admin site at different Netlify site. Don't host the website there, just an admin site. Why not? You don't want to have the same website running at two different URLs. Netlify offers password authenticated sites as paid feature.

Create custom build command and publish directory. The publish directory contains files from admin directory and public_folder. Otherwise, image preview won't work!

#!/usr/bin/env sh

set -e
set -u

DIR="$(dirname $0)/../build-admin"

run () {
    echo $DIR
    mkdir -p $DIR
    build_middleman
    create_admin_site
    ls -lA $DIR
}

build_middleman () {
    middleman build
}

create_admin_site () {
    mv build/admin/index.html $DIR
    mv build/admin/config.yml $DIR
    mv build/public $DIR
}

run

Configuring GitLab Auth

Don't forget to configure Gitlab auth, so users can log in directly with their GitLab account.

Create an OAuth app in GitLab.
Add the Gitlab Authentication provider in Netlify site dashboard

If your site is already hosted at Netlify you can skip creating special admin site. Just configure GitLab OAuth app.

Summary

Services

production site isn't running at Netlify - http://www.sokolmorasice.g6.cz
admin site is running at Netlify - https://sokolmorasice.netlify.com
GitLab repository - https://gitlab.com/sokolmorasice/web

Flow

Invite an editor to GitLab repository (he must have push access)
Editor goes to admin site with Netlify CMS
1. logs in with GitLab account
2. edits some article
Netlify commits a change to GitLab repository
1. GitLab CI deploys changes to production site
2. Netlify rebuilds admin site after GitLab webhook