Middleman

This guide will help you get started using Decap CMS and Middleman.

Installation

To get up and running with Middleman, you need both the Ruby language runtime and RubyGems installed on your computer. Check out the Middleman installation docs for more details. If you already have your environment set up, use the following command to install Middleman:

gem install middleman

Create a new Middleman site

Let's create a new site from scratch. Run the following commands in the terminal, in the folder where you'd like to create the blog:

middleman init blog
cd blog

Add the Middleman blog extension

Middleman has an official extension to support blogging, articles and tagging. middleman-blog ships as an extension and must be installed to use. Simply specify the gem in your Gemfile:

gem "middleman-blog"

Install the dependencies and run Middleman with the following commands:

bundle install
middleman server

Get started with Middleman

Now we have our site up and running let's open up a code editor and create a new folder source/posts and add your first article named 2019-01-01-example-article.html.md with the following content:

---
title: Example Article
date: 2019-01-01
---

This is an example article. You probably want to delete it and write your own articles once you finished this guide!

Activate the blog extension

We can then activate the blog in config.rb. Be sure to check out the Middleman blogging docs for all the configuration options.

activate :blog do | blog |
  blog.permalink = "blog/{title}.html"
  blog.sources = "posts/{year}-{month}-{day}-{title}.html"
  blog.layout = "blog-layout"
end

Load the articles

Time to load our articles in index.html.erb.

<h1>Recent articles</h1>

<% blog.articles.each do | article | %>
  <article>
    <h2>
      <%= article.title %>
    </h2>

    <%= link_to 'Read more', article %>
  </article>

<% end %>

Add an article layout

In the last step before we add Decap CMS, we add a layout for the article page. Create a new layout source/layouts/blog-layout.html.erb. For now we will get the title and the content:

<h1>
  <%= current_page.data.title %>
</h1>

<%= yield %>

Now that we have a functioning blog, let's get started with Decap CMS!

Add Decap CMS to your site

Create two files in a new folder called admin, index.html and config.yml. Also add an upload folder in the images directory that will function as our media_folder.

├── source
│   ├── admin
│   │   ├── index.html
│   │   ├── config.yml
│   │
│   ├── images
│   │   ├── uploads

In the newly created index.html we add scripts for Decap CMS and the Netlify Identity Widget:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="x-ua-compatible" content="ie=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>Decap CMS</title>
    <script src="https://identity.netlify.com/v1/netlify-identity-widget.js" type="text/javascript"></script>
  </head>
  <body>
    <script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js" type="text/javascript"></script>
  </body>
</html>

Configuration

For the purpose of this guide we will deploy to Netlify from a GitHub repository which requires the minimum configuration. In config.yml file paste the following code:

backend:
  name: git-gateway
  branch: main # Branch to update (optional; defaults to master)

media_folder: source/images/uploads
public_folder: /images/uploads

collections:
  - name: blog
    label: Blog
    folder: source/posts/
    extension: .html.md
    format: frontmatter
    create: true
    slug: '{{year}}-{{month}}-{{day}}-{{title}}'
    fields:
      - {label: Title, name: title, widget: string}
      - {label: Publish Date, name: date, widget: datetime}
      - {label: Body, name: body, widget: markdown}

Push to GitHub

It's now time to commit your changes and push to GitHub.

git init
git add .
git commit -m "Initial Commit"
git remote add origin https://github.com/YOUR_USERNAME/NEW_REPO_NAME.git
git push -u origin main

Add your repo to Netlify

Go to Netlify and select 'New Site from Git'. Select GitHub and the repository you just pushed to. Click Configure Netlify on GitHub and give access to your repository. Finish the setup by clicking Deploy Site. Netlify will begin reading your repository and starting building your project.

Enable Identity and Git Gateway

Netlify's Identity and Git Gateway services allow you to manage CMS admin users for your site without requiring them to have an account with your Git host or commit access on your repo. From your site dashboard on Netlify:

Go to Settings > Identity, and select Enable Identity service.
Under Registration preferences, select Open or Invite only. In most cases, you want only invited users to access your CMS, but if you're just experimenting, you can leave it open for convenience.
If you'd like to allow one-click login with services like Google and GitHub, check the boxes next to the services you'd like to use, under External providers.
Scroll down to Services > Git Gateway, and click Enable Git Gateway. This authenticates with your Git host and generates an API access token. In this case, we're leaving the Roles field blank, which means any logged in user may access the CMS. For information on changing this, check the Netlify Identity documentation.

Start publishing

It's time to create your first blog post. Login to your site's /admin/ page and create a new post by clicking New Blog. Add a title, a date and some text. When you click Publish, a new commit will be created in your GitHub repo with this format Create Blog “year-month-date-title”.

Then Netlify will detect that there was a commit in your repo, and will start rebuilding your project. When your project is deployed you'll be able to see the post you created.

Be sure to checkout the official Middleman Starter for more examples.