Back to all blogposts

Static site generators (3/3) – content management with Netlify CMS

Andrzej Herok

Andrzej Herok

Operations Manager

With the emergence of modern static site generators, this type of websites is getting popular again. Being lightweight, simplistic in features and quick to set up, they are perfect for blogging or as a website for an open-source project. But for non-technical individuals, using a static website everyday may prove too difficult. In the final part of my static site generator tutorial, I’m showing you how to add CMS functionality to make management easier.

In the previous parts of my static site generator tutorial, we have created a static site with Hexo and then we’ve pushed it to the web. The tutorial may seem complete, since the website is available publicly. Yet, it still lacks a crucial feature – content management for the masses.

As I’ve mentioned before, the default editorial flow for the majority of static site generators may become a little cumbersome for people that are not tech-savvy. We’d need to teach them the Markdown syntax and tell them a few words about Git versioning (push commands are required) as well as about all the multiple steps required to complete trivial tasks such as writing a blog post.

Static site content management – how does it work?

Luckily, static site generators became so popular that we’ve got plenty of options to facilitate all this without the hassle. In this tutorial, we’ll focus on an alternative called Netlify CMS. Why is that? Because it’s open-source, self-hosted and under active development by Netlify – our favorite static sites hosting solution!

You may be wondering: how do CMSes for static site generators work? Well… It depends, but most of them will connect to your GitHub repository and save the modified files directly to it. Once the changes are pushed, Netlify CMS takes over the job of updating the website’s content.

Netlify CMS – setup 

As I mentioned before, we’re going to use Netlify CMS to create our admin panel. The CMS itself is being distributed as a JS script file (well, that’s not the only option, but that’s the easiest one) that may be loaded in any HTML file. Let’s prepare an HTML file that will be our entrypoint for the admin. 

We want the panel to be accessible publicly (don’t worry about privacy, we’ll take care of authentication later). Let’s put it under the /cms_admin/ URL of our website. In order to do that, first we’ll need to update the Hexo config file. By default, Hexo parses all files under the source directory and converts them using included plugins. We don’t want our admin files to be converted in any way so we need to make sure Hexo will pass the conversion. In the _config.yml file, insert:

- "cms_admin/*"

This will inform Hexo that all the content inside the cms_admin dir should not be rendered or transformed by the tool, but simply copied to the destination directory. 

Now, let’s create an index.html file inside the newly created source/cms_admin directory and paste the following content to our entry file:

As you can see, the file is pretty straightforward. The only actual thing it does is loading the JS file that contains the CMS app. 

When you run the app now and head to the http://localhost:4000/cms_admin/   URL, you should see the the “Error loading the CMS configuration” message. That’s a good sign. We’re going to need to prepare a configuration file for our panel to work. Let’s create a file named config.yml inside the source/cms_admin dir and put the configuration inside.

The configuration can be split into three parts which we’ll explain separately:

  1. Repository information and authentication method.
  2. Directories and the corresponding URL’s configuration.
  3. Content configuration.

Repository info

Let’s paste the first part into the config.yml file:

  name: gitlab
  repo: /
  auth_type: implicit

The backend option is almost self-explanatory. It defines where the repository is located and how to authenticate with it. We’ll use a Gitlab repository and an implicit authentication, which is the simplest way of authenticating as it doesn’t require running a separate OAuth service (we use the Gitlab one).

More information about authentication alternatives can be found in the documentation.

To generate the APPLICATION_SECRET value, you’ll need to create an OAuth application config inside Gitlab settings. In order to do that, go to the Settings page of your Gitlab account and create a new Application under the Applications tab. After creating it, you should get your APP ID value in the next screen.

Media handling

Let’s move on to the second part of the config file. Paste the following options:

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

The entries above define how to handle media paths:

  • media_folder defines where to find images that we can use inside our posts.
  • public_folder defines what will be the public URL of images.

If you’re not convinced about keeping all media files in the repository, there’s also a way to host your images using CDN services. You can find more information in the docs, but for the sake of brevity we’ll use the default variant – keeping all media files inside the repository.

Posts structure

We’ve got one more thing to configure – the structure of our posts for the editor to know which data we want to save into our Markdown content files. Let’s take a look at the last post that we’ve created in the previous article to get to know what types of data we need to handle in our CMS:

title: My Second post!
date: 2020-04-01
tags: [welcome, gallery]
    alt: First image
    alt: Second image
    alt: Third image
This is a test for my new Hexo website!
Tutorial on [TSH Blog]( rocks!

Going from the top we can distinguish:

  • title: a text value,
  • date: date value,
  • tags: a list of text values,
  • images: a list of objects that contain a text value and a URL
  • body: the last, yet the most important part – the Markdown.

Luckily, all the required data types are handled automatically by our CMS of choice so we can just define the fields in the YML config file. Let’s create a whole definition for our CMS. Paste the following content to have all the required fields covered:

  - name: "post"
    label: "Post" # Used in the UI
    folder: "source/_posts" # The path to the posts
    create: true # Allow users to create new posts
    slug: "{{slug}}" # Filename template
      - { name: "title", label: "Title", widget: "string" }
      - { name: "date", label: "Date", widget: "datetime" }
      - { name: "tags", label: "Tags", widget: "list" }
      - name: images
        label: "Images"
        label_singular: "Image"
        widget: list
          - { label: "Alt", name: "alt", widget: "string" }
          - { label: "URL", name: "url", widget: "image" }
      - { name: "body", label: "Body", widget: "markdown" }

As you can see, the collections option defines a list of content types that are available to edit. It’s important to know that Netlify CMS handles multiple content types at once and for each of them the fields structure may be defined separately. We’ll use only one type – post – but if you’d like, you can copy-paste the inside structure and adjust the new structure for videos, announcements and more.

Most of the options are self-explanatory and the real magic happens in the fields option. 

This is the heart of the CMS as this setting defines all the metadata that we’ll be able to edit in each of our posts. 

The widget field informs our CMS how the input field should look like. Netlify CMS comes with plenty of Netlify CMS custom widgets defined out of the box (take a peek in the docs), but if you’d like, you can also use your own ones.

Now that it’s configured (you can review the whole file here), it’s time for a test drive!

Run the website and enter the CMS URL (http://localhost:4000/cms_admin/). You should see a login prompt:

A screenshot shows a login prompt in Netlify CMS

Click the login button and authorize yourself using your Gitlab account. If all goes well, you’ll see a list of your posts, much like the one below:

A screenshot shows a list of posts in Netlify CMS

What should we do now?! Let’s edit some text with our freshly configured CMS! To do that, click the post you want to edit and customize data in the next screen.

A screenshot shows how to edit posts with Netlify CMS

When you make all the changes you want, click the Publish button and see the magic happen! Your edited information should be available live (well.. you’ll still need to wait for a few minutes so that your updated website gets built).

Conclusions – static site management with Netlify CMS

Let’s recap how the Netlify CMS works:

  1. The CMS is authorized to access your repository (you gave it such permissions by authorizing using your Gitlab account)
  2. Editing a post or creating a new one (via the Publish button) creates a new commit in the repository. It contains all the changes you made.
  3. Each publish action requires time to rerender the whole website.
  4. When it is done, the website works flawlessly without the need of any server-side logic.

This was the last part of the Static Site Generators tutorial. By now, you should know how to create, deploy and manage such websites with Netlify. Most of this advice should also work with various Netlify alternatives. Although the whole tutorial is pretty straightforward, a repository with all the changes may still come in handy. Enjoy.

You may also like

State of Frontend 2022 - Global report

With 3700 devs, 19 experts, 13 topics. This report will rock your front!

Claim free copy

What would you like to do?

    This site is protected by reCAPTCHA and the Google
    Privacy Policy and Terms of Service apply.

    They are more than just a software company. They are the partner who will help you achieve what you want to achieve.

    Nick Gold

    Managing Director at Speakers Corner


    Thank you for your inquiry!

    We'll be back to you shortly to discuss your needs in more detail.