How to Deploy a Nikola Static Site on Cloudflare Pages: A Step-by-Step Guide

Diego Carrasco G. — Thu, 07 Dec 2023 08:00:00 GMT

Table of Contents

Context: Nikola Static Site Generator

Static websites have become increasingly popular in the web development world for their speed, security, and simplicity. Nikola, a widely-used Python-based static site generator, facilitates the creation of content-rich yet lightweight websites.

You can use many markup-languages allowing you to choose the ones you like the most. You can even write some articles in Markdown, some in Asciidoc, some in reST and some in HTML, and Nikola will process them accordingly.

There are many other SSGs (Static Site Generators) out there, like Jekyll, Hugo, Eleventy, Gatsby, Hexo, MkDocs, Pelican, Zola, and many more. I’ve tried many of them (at list all them in the list above,) and I’ve found Nikola to be the best for my needs.

Your needs might be different, so I encourage you to try them all and choose the one that fits you the best. If in doubt, I recommend you to start with Nikola.

If you write all your content in Markdown, you can write a couple of articles and try each framework out there. The only thing you may have to change is the metadata format.

Anyway, this article is not about Nikola, but about how to deploy a Nikola site on Cloudflare Pages. and the steps described here can be applied to any other SSG, as long as you use the correct file for their dependency manager.

There is a list of supported SSGs (Frameworks) in the Cloudflare Pages documentation.

Hosting options like GitHub Pages, GitLab Pages, and Cloudflare Pages provide free, reliable and fast platforms for these kind of sites.

Why Cloudflare Pages?

Cloudflare Pages stands out, in my opinion, for:

its performance optimization and enhanced security (includes a basic WAF - Web Application Firewall - and DDoS protection),
its integration with their awesome DNS management,
integrated analytics (although with data for the last 30 days only),
its integration with Cloudflare CDN and proxy,
its free subdomain under pages.dev (if you need one),
its free SSL certificate,
its multi-branch deployments (meaning you can deploy different branches to different subdomains and check if everything looks like you want before merging to master. You can also always re-deploy an old commit), and
its support for custom domains,

making it an excellent choice for hosting Nikola sites (or any kind of static sites, actually).

But the main reason I chose Cloudflare Pages is that it has Deploy hooks!

What are Deploy Hooks? → Automatic scheduled posts in static sites!

Deploy hooks are URLs that you can use to trigger a new deployment of your site. This is useful when you want to automate the deployment of your site, for example, when you push a new commit to your repository, or when you use Nikola to schedule posts in the future.

With deploy hooks I can set up a Zap in Zapier or a Flow in ActivePieces to trigger a rebuild of my site (event when there is no new commits to the repo) and, because of the date Nikola will publish automatically the new scheduled post.

Yes, I can have dynamism in my static site!

This means:

I can schedule posts in the future (meaning I can write 4 articles in a week and publish them once a week at the right time. This is good for me because I often write in batches or spurts of energy, interests and time).
I can have a Zap (in Zapier) or a Flow (in ActionPieces) that will trigger a rebuild of my site every day at 10:00, so I can have a new post published every day at 10:00 (or 10:05, depending on the speed of the rebuild).

I will get into more detail about this in a future post.

Step-by-Step Guide to Deploying on Cloudflare Pages

Step 1: Setting Up Your Environment

A Pipfile is essential for deploying on Cloudflare Pages, as it manages your Python dependencies.

This file’s contents will depend on the specific configurations and input formats of your Nikola site, such as Markdown, Asciidoc, or reST.

The Pipfile is used by the Pipenv tool, which is used to manage Python dependencies and virtual environments.

In this article I write also about a Gemfile, which is used by the Bundler tool, which is used to manage Ruby dependencies and virtual environments. I added this because I use asciidoctor (Ruby-based) to process my Asciidoc files.

Both files (Pipfile and Gemfile) have to be in the root of your repository.

Sample Pipfile

This sample Pipfile includes the dependencies for a Nikola site using Markdown and Asciidoc. You may update the versions as needed.

[[source]]
url = 'https://pypi.python.org/simple'
verify_ssl = true
name = 'pypi'

[requires]
python_version = '3.7'

[packages]
Nikola = '8.2.2'
markdown = '3.3'
asciidoc = '10.2.0'
pygments = '2.13.0'
jinja2 = '3.1.2'

Configuring Asciidoc in Nikola (optional)

Configuring Asciidoc in Nikola involves specifying the binary path and options in the conf.py file.

In this case I want to use asciidoctor as the binary and I want to have a table of contents and use Font Awesome icons when processing the file.

ASCIIDOC_BINARY = "asciidoctor"

# Specify options to the asciidoc compiler (as a string).
ASCIIDOC_OPTIONS = "-a toc -a icons=font -a icon-set=fa"

Sample Gemfile

For Nikola sites using Asciidoc, a Gemfile is also required to ensure proper processing of Asciidoc files.

source 'https://rubygems.org'
gem 'asciidoctor'

Step 2: Link Your Repository

Sign in to Cloudflare Pages.
Choose 'Workers and Pages' from the left sidebar.
Click the tab 'Pages'.
Clock "Connect to Git" to connect your GitHub or GitLab account.
Select the repository containing your Nikola site.
Configure the build settings as per your project’s needs.

And that’s it!

Happy deploying!

Diego A. Carrasco Gubernatis | Personal Website (Posts about cloudflare pages)