How I got DecapCMS and Hugo Working

May 14, 2025

I’ve been trying to get DecapCMS working with my Hugo site locally without having to rely on netlify while keeping everything locally.

My goal is just to run DecapCMS on top of my Hugo site whose git repository is hosted locally. I want Decap to just modify/create new hugo posts in my local git repository without having to interact with anything external.

After wrangling with the official documentations, this is how I actually got Decap UI and Hugo working together locally.

Prerequisite

You need to have netlify-cms-proxy-server locally to act as a proxy server

Install Netlify-CMS-Proxy-Server

This is needed to act as a file proxy server that will load your local file system to load and save your posts that you create via decap-ui. This also skips all sort of authentication for your local use.

To quickly setup, just install via

$ npm install -g netlify-cms-proxy-server

Then run the following in the root directory of your hugo project.

$ netlify-cms-proxy-server

This is because, where you run netlify-cms-proxy-server is what it will take reference of the files to be edited and changed by the UI.

Once setup and run, this server will listen (by default) at http://localhost:8081. Ensure that this is loaded on the same server/system as your local git repository as its job is to modify your local filesystem for editing purposes.

Install Decap UI

First, in your hugo site, create these 2 new files in your /static/admin/ directory

/static/admin/index.html


<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="robots" content="noindex" />
    <title>Content Manager</title>
  </head>
  <body>
    <!-- Include the script that builds the page and powers Decap CMS -->
    <script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
  </body>
</html>

/static/admin/config.yml

backend:
  name: proxy
  branch: master
  proxy_url: http://localhost:8081/api/v1
  local_backend: true

local_backend: true
media_folder: "static/images/uploads"
public_folder: "/images/uploads"

collections:
  - name: "posts"
    label: "Blog Posts"
    folder: "content/posts"
    create: true
    slug: "{{slug}}"
    fields:
      - { label: "Title", name: "title", widget: "string" }
      - { label: "Publish Date", name: "date", widget: "datetime" }
      - { label: "Body", name: "body", widget: "markdown" }

Take note, you will want to adjust branch, proxy_url and the various collections here according to your own configuration

proxy_url : this will be the url that you need to insert to connect to netlify-cms-proxy-server. Ensure this is correctly referenced.

backend.name must be set to proxy. This is what actually got me into circles as many documents seem to reference using git-gateway with local_backend but I found that the correct backend to use is proxy.

Lets Run

With this, when you run hugo server, you can view decap-ui at /admin. Once you edit a file and save, you will see the file modified.