Configure Your Blog with Decap CMS

This starter ships with a Git-based blog powered by Decap CMS. This guide walks you through how the blog is wired, how to configure the post fields, how to connect a login for your client with DecapCMS, and how posts get published, every edit lands back in your GitHub repo as a commit.

Before You Start

Make sure you've read the initial setup guide.

See Quick Setup

How Setup Works

Understand

See how Decap CMS, markdown posts, and the admin config fit together

Configure

Set the blog collection and post fields in config.yml

Connect

Wire up DecapBridge login with a GitHub token

Publish

You and your client write posts from the /admin dashboard

How the Blog Works

Decap CMS is a Git-based CMS, there's no database. Every post is a markdown file in your repo, and three folders do all the work.

src/
├─ admin/
│  ├─ config.yml          ← CMS configuration (collection, fields, backend)
│  └─ index.html          ← loads the Decap dashboard at /admin
├─ content/
│  └─ blog/
│     ├─ blog.json        ← layout + permalink applied to every post
│     ├─ my-first-post.md ← one markdown file per post
│     └─ ...
└─ assets/
   └─ images/
      └─ blog/            ← featured images uploaded from the CMS

src/admin/config.yml

Defines your collection, the fields each post has, and which backend handles login.

src/content/blog/

One markdown file per post. The CMS creates, updates, and deletes files here.

src/assets/images/blog/

Where featured images land when uploaded through the dashboard.

Edits become commits

When someone saves a post in the dashboard, Decap commits the markdown change to your GitHub repo. That commit triggers a rebuild on your host, and the new post goes live, no manual deploy needed.

Configure the Blog Collection

The collection in src/admin/config.yml controls the folder posts are saved to and the fields editors fill in.

The starter already includes the blog collection below. The defaults work out of the box, adjust labels, add fields, or change the upload folders to fit your project.

# Image upload folders
media_folder: "src/assets/images/blog"
public_folder: "/assets/images/blog"

# The blog collection
collections:
  - name: "blog"
    label: "Blog"
    folder: "src/content/blog"
    create: true
    slug: "{{slug}}"
    fields:
      - { label: "Title", name: "title", widget: "string" }
      - { label: "URL Slug", name: "url", widget: "string", hint: 'Specify where the page will be written to. If you use "Blog Post", the post will be accessible from "blog/blog-post"' }
      - { label: "Description", name: "description", widget: "string" }
      - { label: "Author", name: "author", widget: "string" }
      - { label: "Date", name: "date", widget: "datetime" }
      - { label: "Tags", name: "tags", widget: "list", default: ["post"] }
      - { label: "Featured Image", name: "image", widget: "image" }
      - { label: "Image Caption", name: "imageAlt", widget: "string" }
      - { label: "Body", name: "body", widget: "markdown" }

What each field does

Titletitlestring

The post headline.

URL Slugurlstring

Where the post is written to, "My Post" becomes /blog/my-post/.

Descriptiondescriptionstring

Short summary used in listings and SEO meta tags.

Authorauthorstring

Name shown as the byline.

Datedatedatetime

Publish date, used for sorting.

Tagstagslist

Defaults to "post" so Eleventy collects it into the blog.

Featured Imageimageimage

Uploaded to src/assets/images/blog.

Image CaptionimageAltstring

Alt text for the featured image.

Bodybodymarkdown

The post content, written in rich-text markdown.

Where images go

media_folder is where uploaded files are stored in the repo, and public_folder is the path written into your markdown. Keep them pointed at the same blog folder so featured images resolve correctly on the live site.

Post Layout & Permalink

A directory data file gives every post its template and URL, so editors never have to think about it.

Markdown files can't set their own layout or permalink, so src/content/blog/blog.json applies these settings to every post in the folder. It picks the post.html layout, tags each entry post so Eleventy collects it, and builds the URL from the post's url field.

{
  "layout": "layouts/post.html",
  "tags": "post",
  "eleventyComputed": {
    "preloadImg": "{{ image }}",
    "permalink": "/blog/{{ url | slugify }}/index.html"
  }
}

What a post file looks like

Each post the CMS creates is a markdown file with frontmatter matching the fields you configured, followed by the body. You can also create posts by hand using this shape:

---
title: My First Post
url: my-first-post
description: A short summary of what this post is about.
author: Your Name
date: 2026-06-24T12:00:00.000Z
tags:
  - post
image: /assets/images/blog/landing.jpg
imageAlt: Descriptive alt text
---

Write your post here using **markdown**.

Connect Login with DecapBridge

To let you and your client log in without the deprecated Netlify Identity, create a free DecapBridge site that bridges to your repo.

1.Navigate to decapbridge.com and create an account. It's free.
2.Open the dashboard and click Create New Site. You'll be asked to fill in three input fields.

GitHub repository

Must be in user-or-org/repository-name format, e.g. your-name/your-blog.

GitHub access token

A fine-grained personal access token (see the next section for how to create one).

Decap CMS URL

The deployed URL of your admin dashboard, e.g. https://your-site.netlify.app/admin/#/.

Create a GitHub Access Token

DecapBridge needs a fine-grained token to read your markdown and open pull requests with new content.

1Log into your GitHub account.
2Click your profile picture (top right, not the repository profile) and click Settings.
3Scroll down and click Developer Settings.
4Click Personal access tokens and choose Fine-grained tokens.
5Click Generate new token and provide your password again if required.
6Provide a name for the token in the Note field.
7Set the token’s Expiration to "No expiration".
8Set Repository access to the desired repository only.

Repository permissions

Under Permissions / Repository permissions, set Read and write access for this repository's Contents and Pull requests. This lets Decap CMS read your markdown and write new content via pull requests.

9Double-check the permissions, then click Generate token.
10Copy your token now, you will not be able to see it again.

Don't lose the token

The token is shown only once. Copy it before leaving the page and paste it straight into the DecapBridge GitHub access token field.

Swap in the Backend Snippet

Replace the placeholder backend in your admin config with the snippet from your DecapBridge dashboard.

Out of the box, src/admin/config.yml ships with a placeholder backend: git-gateway so the CMS loads locally. Replace that whole backend block with the snippet from your DecapBridge dashboard. The repo, identity_url, and gateway_url values are all generated for you. It should look something like this:

# Use DecapBridge auth (required)
backend:
  name: git-gateway
  repo: your-name/your-blog # provided by decapbridge
  branch: main
  identity_url: https://auth.decapbridge.com/sites/<your-site-id> # provided by decapbridge
  gateway_url: https://gateway.decapbridge.com # provided by decapbridge

  # Quickly see who did what (optional)
  commit_messages:
    create: Create {{collection}} "{{slug}}" - {{author-name}} <{{author-login}}> via DecapBridge
    update: Update {{collection}} "{{slug}}" - {{author-name}} <{{author-login}}> via DecapBridge
    delete: Delete {{collection}} "{{slug}}" - {{author-name}} <{{author-login}}> via DecapBridge
    uploadMedia: Upload "{{path}}" - {{author-name}} <{{author-login}}> via DecapBridge
    deleteMedia: Delete "{{path}}" - {{author-name}} <{{author-login}}> via DecapBridge
    openAuthoring: Message {{message}} - {{author-name}} <{{author-login}}> via DecapBridge

# Better Decap + Bridge logo (optional)
logo_url: https://decapbridge.com/decapcms-with-bridge.svg

# Add site links in DecapCMS (optional)
site_url: https://your-site.netlify.app

Push and test

Push the change to your repo and test the authentication system. As the admin of the site, your login credentials for the Decap dashboard are the same as your decapbridge.com credentials.

Publish Posts from /admin

This is the day-to-day workflow your client will use, no code, no terminal.

1Go to https://your-site.com/admin/ and log in with the DecapBridge credentials.
2Open the Blog collection and click New Blog.
3Fill in the Title, URL Slug, Description, Author, Date, and Tags, then upload a Featured Image and write the body in the markdown editor.
4Click Publish. Decap commits a new markdown file to src/content/blog/, your host rebuilds, and the post appears at /blog/your-slug/.

Invite your client

In your DecapBridge dashboard, add your client as a collaborator. They get their own email and password, they never need a GitHub account to publish.

Preview before publishing

The editor shows a live preview pane next to the form, so your client can see exactly how the post will look before they hit Publish.

Editing locally (optional)

The config keeps local_backend: true, so you can edit content on your machine without logging in. In one terminal run npx decap-server, start the site with npm start in another, then open localhost:8080/admin/.

Your Blog Is Live

Decap CMS now powers your blog and DecapBridge handles the logins. You and your clients can sign in at the /admin dashboard, and every edit lands back in your GitHub repo as a commit.

Decap CMS Docs Deployment Guide