× Search About Posts Code Music Links
Blank Try
experiment
lots
learn
more

Setting Up Decap CMS

Updated on
Last site update: 8 May 2024

Table of Contents

Unfinished article

How it works

Netlify CMS is runs as a single page web app on your site that can access and edit the content sections of the site’s Git repo. Because this part of the site does not need to be processed by Hugo these files are kept in the static folder. A folder at /static/admin can then be accessed at www.example.com/admin on your site. The simple CMS page, index.html is actually a React app that uses React code from a CDN or kept locally.

What you need

You need an unbuilt static site on GitHub, GitLab or BitBucket that is built and hosted by Netlify. These can all be used for free.

Demo version

If you want to get an idea of whta the CMS is like there is online demo version that doesn’t even require a login.

Netlify CMS demo

Setup in brief

Here are the main steps to setup the CMS when hosted on Netlify:

On your site

  1. Add a folder called admin to your project’s static folder and add two files: an index.html file and config.yml (NOT config.yaml).
  2. Add two <script> tags to this index.html file. The first, for a netlify identity widget, is added to the <head> section. The second, the react script for the CMS, is added to the <body> of your page. The netlify one is:
1    <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>

For the CMS you can use either of the following:

1<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js">
2<script src="https://cdn.jsdelivr.net/npm/netlify-cms@^2.0.0/dist/netlify-cms.js">
  1. Add the script tag for the Netlify Identity widget (above) to the <head> of your site’s main index.html page. (This can also be done using Netlify’s script injection feature)
  2. Add another short script just before the closing <body> tag of your site’s main index.html page:
 1<script>
 2  if (window.netlifyIdentity) {
 3    window.netlifyIdentity.on("init", user => {
 4      if (!user) {
 5        window.netlifyIdentity.on("login", () => {
 6          document.location.href = "/admin/";
 7        });
 8      }
 9    });
10  }
11</script>

On Netlify

  1. Enable Git Gateway. From the Netlify interface for your website go to site configuration (the second menu item). From here click on identity in the vertical menu then press the Enable Identity button.
  2. Under registration press configure and choose whether you want Open or Invite only.
  3. Scroll down to services and click on enable git gateway.
  4. Next click on integrations in the main menu then on identity. invite at least one user to be able to login into the CMS. The email provided will get a login link which will take you to the CMS where you’ll be prompted for a password of choosing.
  5. Setup the admin/config.yml file. See the Netlify CMS config article for how to do this.

More detailed info

On the hosting side you need to set up authentication so that the CMS can access and make commits to your repo.

Although Netlify CMS is an open source project it is, at this time, easier to set up with a Netlify hosting account and is slightly better for some features if kept on GitHub.

The Netlify account makes it simple to set up authentication from GitHub. You can find this in the Netlify interface under the Site Settings > Identity > Services section of the specific site (see below).

One click install

You can use a template specific to your static site generator and install with just a few clicks from here.

However setting up with a Hugo site that is already built and hosted by Netlify is fairly easy.

In your site’s project folders

You need to:

  1. Add an admin folder to the /static/ folder of your site.
  2. Add two files to this, and index.html file and a config.yml file.

If the index.html file has a link the Netlify CMS script at a CDN you don’t need to do anything else.

If you don’t want to use a CDN for Netlify CMS it’s also possible to install it using NPM.

From Netlify

You can generate the access token from within the Netlify interface. From the site’s settings (far right end of the menu) click on Idenity then Services to find the Git Gateway section. Click on the enable Git Gatewy button. Very easy and that’s it done!

From GitHub

But you can also generate a new token from GitHub. Go to your GitHub account settings in the top right dropdown. From there choose Developer settings near the bottom of the list. Here you can choose Personal access tokens and press the Generate new token button. Copy this immediately as you cannot reaccess it again. You then need to paste it into your Netlify project settings.

To generate a PAT (personal access token) from GitHub click on your profile pic (top right) and choose settings. These are different from the settings for each repo. From there scroll down a click on the the Developer settings button near the bottom.

GitHub developer settings button

From here you can choose Personal Access Tokens and click generate a new token.

GitHub Personal Access Tokens section

Add a note and set the expiration date and click the sections on the form.

Expiration of access tokens

From GitHub:

As a security precaution, GitHub automatically removes personal access tokens that haven’t been used in a year. To provide additional security, we highly recommend adding an expiration to your personal access tokens.

More on Netlify Identity in Netlify docs

Creating a personal ccess token on GitHub

Adding Hugo shortcode menu to the CMS UI

There’s another script that adds a menu dropdown to the rich text options of the CMS UI.

1<script src="https://sharadcodes.github.io/hugo-shortcodes-netlify-cms/dist/hugo_shortcodes_netlify_cms.js"></script>

If you add this to the static/admin/index.html file BELOW the CMS script in the <body> section of the page.

Then in the UI for editing a page you get this selection:

Hugo shortcodes dropdown menu

The link above is a Javascript file made up of different blocks for each shortcode and uses the CMS.registerEditorComponent for each block. Here is the code for Hugo’s built in <figure> element shortcode:

 1CMS.registerEditorComponent({
 2    id: "figure",
 3    label: "Figure",
 4    fields: [{
 5            name: "title",
 6            label: "Figure Title",
 7            widget: "string"
 8        },
 9        {
10            name: "src",
11            label: "Figure SRC",
12            widget: "string"
13        },
14    ],
15    pattern: /

      
([a-zA-Z0-9-_ ]+)

    



/,
16    fromBlock: function(match) {
17        return {
18            title: match[1],
19            src: match[2],
20        };
21    },
22    toBlock: function(obj) {
23        return `

      
${obj.title}

    



`;
24    },
25    toPreview: function(obj) {
26        return `<figure><img src=${obj.src} alt=${obj.title}><figcaption>${obj.title}</figcaption></figure>`;
27    },
28});

See the GitHub page for this code.

GitHub GraphQL API

One of the new beta features that can be used is the new GitHub GraphQL API.

See also: Netlify CMS Configuration

▲

External links