How to Add a Headless CMS to a Pelican Static Site

Posted by Luan Nguyen on September 26, 2023

Have you ever gotten so frustrated with your company's bloated and fragile Wordpress site, and hoping to find a faster and more stable option? Static site generators has been suggested by many as the way to go but it probably hasn’t crossed your mind since it doesn't seem like the right fit for your non-technical marketing team members to be able to use.

In this article, you'll find the pros and cons of static sites, and a simple way to make it work, both for you the team developer to maintain, and for your marketing colleagues to write and publish great content.

What are static site generators?

Static site generators help take your articles and turn them into a complete, static website.

Sounds familiar? Well, isn't Wordpress the same?

Yes, Wordpress also helps create a website from your articles. However, the key difference here is "static", compared to "dynamic" site, which is what Wordpress is.

To understand this, let's first look at how a dynamic site, like Wordpress, normally works.

When a user accesses a Wordpress website, the web server application will need to run Wordpress code (in PHP). The code will read the database for content, then put that into a specific template to build the page, before serving it to that user. This happens for every single request made by users to the site, even it's the same page.

In contrast, pages in a static website are, as its name suggests, "static". That means when users access the site, the web server application just takes the page, and serves it to the user, without going through the whole building process again. 

Why use a static site generator or a static website?


Based on the explanation above, obviously static websites are fast, extremely fast. They eliminate all the need for complex building processes when users make requests since everything has been done previously. So each time a user requests for a page on the website, the server just needs to return the result. It's that simple.

Better User Experience

Who wants to wait forever just to read an article? If your site takes more than 3 seconds to load, you can expect to have up to 40% of users go away. And the more time your site takes to load, the more prospective sales leads you are throwing away.

Have a faster site speed with a static website will help your search engine ranking which translates to more incoming traffic to your website. 


Imagine one day, you post an article that your marketing team spend days of hard work on promoting and it makes it to the top of Reddit! As you're watching live Google Analytics, the traffic rockets! But just a few minutes later, the traffic suddenly drops and you can't even access your own website. In short, your website can't handle such big traffic.

To serve a dynamic site, your server has to do a lot of work, thus with the same server, you can serve ways more visitors with a static site, than a dynamic site.

Hosting price

Due to the nature of a static website that the server doesn't need to process that much, you only need simple hosting for the website, without any complicated technology. That also means fewer dollars spent on hosting.

There are even static web hosting that are reliable and able to handle relatively high traffic, and FREE, like GitHub Pages.


If you've been using Wordpress, you might notice how often you get updates from Wordpress and Plugins. Besides additional features added in the updates, the majority updates are for fixing the vulnerable code, more than 70% of Wordpress site are vulnerable to attacks.

This is a typical story of dynamic websites since it needs to execute sophisticated code, it will almost certainly have security gaps.

Static sites, in contrast, are different. Static sites are only normal, fixed HTML, CSS and js file. That means, when users access your site, the server just takes it as it is, and passes it back to the users, with no build process. This simple process reduces the dance of breaking in due to the build process.


Wordpress has a big codebase and a huge number of plugins. Almost every time you need something, there's a plugin for that. However, not all plugins are created equal. It's not uncommon when you install a plugin for a small functionality, you realize it breaks the whole site a few days after that.

With a static site, that shouldn't be the case. If you can build it, then it'll just keep running, as long as you keep it there.

So with of all its advantages, why is everyone not switching to static site generators already?

Well, static site generators are not everyone.

It's not friendly for non-tech savvy users

To be able to set up and use (most) static site generators, you need to know how to do fairly sophisticated configuration and run scary commands, which are not something most average people are comfortable doing.

There's no simple, point and click, 5-minute setup like Wordpress.

 And well, after finishing an article, you'll need to run command(s).

 And to publish the content somewhere, you'll most likely need to run command(s) again!

Markdown - The blessing and the curse

Markdown is the most common format you'll need to write your content in, so static site generators can do its job, building the site for you.

Markdown is simple. Markdown is straightforward. So why is it an issue?

Well, even it is simple, it's not for everyone. Average users still prefer editors where they can visually see what you'll get (aka WYSIWYG). And well, isn't it a lot easier to drag a picture in and boom, you have it in an article, instead of managing that yourself, and insert alien stuff like this.

![alt text]( "My awesome image")

Publish on mobile? No thanks

Imagine you're at the airport, waiting for an hour more to board your flight. You might want to take out your iPad, finish up the article you started the night before and publish it.

Well, it isn’t that easy. You might want to use your heavy laptop instead because static site generators are not for mobile users.

Still want static site generator for average users?

With all of those limitations, most people would believe static site generators are only for tech nerds. It wouldn't fit companies where the marketers are the ones who write and publish content. You don't want to get called by those people every single time they want to publish a new article right?

Well, there's some good news. You can enjoy the benefits of static sites, while still allowing most average people to write and publish. In fact, there are quite a few solutions to this, depending on which tech stack you want to use. 

If the developer in your company happens to be familiar with Python, then the combination of Pelican and a headless CMS such as ButterCMS might be worth a try. It will need some initial tech setup, but once the setup is done, everything should be as easy as publishing an article on Wordpress.

Pelican is a popular, python static site generator. It has a pretty big user base, a lot of themes and plugins to select from. This helps you to start a site fast without having to develop anything yourself. ButterCMS is a service to help you write and manage content easily, with a familiar WYSIWYG editor.

But how do these two go together? With a little help of this Pelican plugin.

The idea is, when you publish an article on Butter, it will call a webhook on your server. This webhook will then trigger Pelican to build content and then publish it to your host. The magic happens here, as the plugin will automatically pull content from Butter into Pelican during the build process.

How do you set it up?

First, you need a functioning Pelican site. Pelican has a quick guide on how to set up a fully functional site.

Then you get your API key from Butter CMS.

Install ButterCMS-Pelican plugin for Pelican (guide provided is below)

You will need a small script running on your server, to receive a webhook call from ButterCMS. This script will build and publish the site. You can also have this script to publish your site to Github Pages. You can find examples of the it here.

Install ButterCMS plugin for Pelican

As mentioned above, it is assumed that you have a functional Pelican site.

First, clone ButterCMS-Pelican repository into `plugins` folder

$ cd plugins

$ git clone

You should have a folder structure similar to this


Open `` file, make sure you have set plugin folder path

PLUGIN_PATHS = ["plugins"]

PLUGINS = ["liquid_tags", "sitemap"]

Now add `buttercms-pelican` to plugin list and an additional setting for Butter API key anywhere in the file.

The end result should be similar to this

PLUGIN_PATHS = ["plugins"]

PLUGINS = ["liquid_tags", "sitemap", "buttercms-pelican"]



   'api_key': 'b60a008584313ed21803780bc9208xxxxxxxxxxx'


 And that’s it, it’s that simple to make ButterCMS work with Pelican. You can now generate your site as usual, and all articles from your ButterCMS account will show up on your static site!


We have covered quite a few benefits of static site generators for company websites, like better speed, user experience, security and reliability, which are important factors to improve conversation rate.  However, they are supposedly not friendly for those not familiar with code.

 The dead simple plugin ButterCMS-Pelican, with less than 10 lines of configuration, will help you with just that. It brings the simplicity of managing content on ButterCMS, while still gives you the power of static site generator Pelican.

Read more great Headless CMS tutorials by subscribing to our monthly newsletter.
Luan Nguyen

Luan is a back-end developer, focusing mainly on Python/Django/Django REST and API integration. For more tech-related articles, you can visit his site:

ButterCMS is the #1 rated Headless CMS

G2 crowd review award G2 crowd review award G2 crowd review award G2 crowd review award G2 crowd review award G2 crowd review award G2 crowd review award G2 crowd review award G2 crowd review award G2 crowd review award G2 crowd review award G2 crowd review award

Don’t miss a single post

Get our latest articles, stay updated!