Creating a Static Blog with Search and Comments using the Pelican Static Site Generator

Photo by Taryn Manning on Unsplash

Did you know Pelicans can eat freaking turtles?

No wonder they walk around like badass OGs.

Yeah, pelican, the bird is indeed awesome.

But so is Pelican the static site generator. Especially for whipping up a lean dev blog.

In this tutorial, I’ll show you how to use the Python-powered Pelican static site generator (SSG) to quickly create a sleek blog.

I’ll also spruce things up by adding static comments and a search function to the site.

Note: This isn’t my first rodeo with static sites. I’ve shown our readers how to add e-commerce to Jekyll, Hugo, Gatsby, and many other SSGs. But today, no e-commerce, no Snipcart. I’ll just be covering a plain, simple tutorial for a dev blog! :)

This post will cover:

• How to create a Pelican blog and change its theme
• How to add the Tipue Search plugin
• How to enable static comments with Staticman
• How to host a Pelican site on GitHub Pages

Ready for take-off?

Can I Pelican? (teammates blackmailed me)

Pelican, a Python-powered static generator

Simply put, Pelican is a neat static site generator written in Python.

Like all SSGs, it enables super fast website generation. No heavy docs, straightforward installation, and powerful features (plugins & extendability). Plus, you get all the benefits of a static site: cheap, portable, secure, lightweight, easy to host. As a blogging platform, Pelican also allows you to own all of your content, even comments (thanks to Staticman). No need to rely on trusted third parties like Medium.

With Pelican’s well-crafted CLI, you can generate your site, switch themes, and push content without leaving your console. Perfect for a dev blog!

There’s also a huge open source collection of themes to choose from.

Sidenote: If you’re a Python fan, check out our Django e-commerce tuts with Wagtail!

Pelican Tutorial: a dev blog with comments & search

All right amigos, let’s get to the crux of the matter.

Pre-requisite

• Python installed with pip’s package manager

1. Scaffolding the static blog

The first thing to do is simply scaffold a website using the CLI. It will give us the file structure needed to customize our setup right away.

• create a new folder for your project
• open a console in it
• install Pelican’s Python package with pip install pelican

Once that’s done, use the CLI straight away to do the scaffolding with pelican-quickstart

Here’s how your configuration should look like:

For the demo, I wanted to play around a bit with some themes, so I chose to clone the wholepelican-themes repo. You can do so with git clone git@github.com:getpelican/pelican-themes.git in the folder of your choice.

2. Creating blog content in Markdown

To make this demo less contrived, I used real “open source” content from the Aeon website.

You could decide to generate a new folder to keep content organized. But for the sake of keeping this demo simple, I created everything directly in the content folder.

Fire up your favorite text editor and open the content folder. Create a file nameare-you-just-inside-your-skin-or-is-your-smartphone-part-of-you.md. As you can see, the file extension is .md, so we will use the Markdown format to define our content. A Markdown file is declared with metadata (at the start of the file), followed by the actual content. Pelican's files support many metadata fields. It's worth reading their docs about this here.

Now, back to the file you just created. Open and fill it up with actual content (our Aeon source):

You can repeat this step with all the content you need. Once you’ve got your content, you’ll be ready to generate the blog.

3. Changing the Pelican theme

Go into the folder we cloned earlier, and copy your chosen theme in your project’s root folder. Then, in the same folder, run pelican-themes -i {your_theme_name}.

You’re all set to give your site a first shot. To generate it, again, in the same folder, run pelican -t {your_theme_name}. This will generate your website with the specified theme and put it inside the output folder.

Simply serve the site with whatever suits you. I opted for Node’s http-server. Here's my result at this point, using the monospace theme:

Note: if you want to customize & create Pelican themes, check out its Python templating language Jinja2

4. Adding the Tipue search plugin

Now now, I know there are tons of way to handle search on a static site. Third parties — Algolia, and others. Server-side searches. Client-side searches. Truth is, most of these are overkill for my humble demo. 😏

So to add a search feature to the blog, I’ll use a Pelican-specific search plugin. There are many plugins in this sub-repo, but the one of interest to us here is tipue-search.

Install the required Python package with pip install beautifulsoup4. Next, clone the project's folder, and register it inside your pelicanconf.py file. You'll be able to do so simply by adding the following line: PLUGINS = ['tipue_search.tipue_search']. If you re-generate your website, you'll see a new file named tipuesearch_content.json. That's the static content the search will use. Now, you only need to modify your theme's templates to add the search.

Hop into monospace/base.html — the template used for every page. There, add both jQuery and tipue-search with the following HTML.

Now add this code to the <div id ="sidebar"> section:

And the following JavaScript, again in the same base.html file:

That’s it! You should have static search directly on our website now. Rebuild your blog and see the result. Here’s how my search box and results look:

5. Adding static comments with Staticman

Most people default to Disqus to handle comments on their sites. There’s also a Disqus static comment plugin for Pelican. Now I have no personal beef with Disqus. But I’d be hard-pressed to ignore the number one issue related to trusting this third party, even in its “static” form.

→ Comments are hosted on Disqus servers — no ownership of content.

Staticman solves all of the above. That and, of course, a simple problem most static sites suffer from: adding forms for user-generated content without a backend. Staticman is perfect for reader comments, but also for voting systems or user reviews. For more details on its superpowers, check out this full post by my colleague Jean-Seb aka Mumbledore.

Disclaimer: Snipcart sponsors the Staticman open source project.

So for the sake of transparency, here’s a list of static comment alternatives you might consider.

Now for the technical part.

I will skip the default configuration of Staticman as it is really straightforward and well explained here.

Once, you have a repo with the app as a contributor running, you’ll need to add a configuration file and the necessary templates to send and render data. Create a staticman.yml file with the following content:

Now, hop in monospace/templates/article.html and add the following just after the {{ article.content }} line:

This is the form used to send comments to Staticman. The latter will push them and include them in your repo. This way your website will be able to render them without any external calls.

To first render them, let’s convert these comments in JSON within our templates, since they are in YML at the moment. First, download the pyyml python package with pip install pyyaml.

Once this is done, go to pelicanconf.py. This is where you'll include your comments.

Add these following lines wherever you want:

This will load every .yml comment file, parse it into JSON, and expose them as an array. Any all-caps variable in this file will be exposed inside Jinja2 templates, which means you’ll have access to the comments in any template.

What you want to do now is render the comments on the matching articles. In article.html, add this section just between the {{ article.content }} line and the form we just added:

Here’s a quick look at our static comments.

Now let’s host that static blog!

6. Hosting your Pelican blog on Netlify

I would have liked to host everything on GitHub Pages, as it’s a good fit with Pelican. But since I needed to rebuild the project once a comment is pushed to keep the website updated, I decided to go with Netlify. Once a new comment is pushed, Netlify will be notified, rebuild the website, and host it with the new comment. To do so, add a requirements.txt to your project's folder and add these lines to it:

pelican 
pyyaml 
markdown 
beautifulsoup4

This is the file that will be used by Netlify to download the project’s dependencies. Now, push your code to a repo and hit netlify.com. Once you’re logged in, click the new site from GIT and choose your project's repo with these settings:

The deploy will start right away, and your website should be live in a minute! Note that the site has to rebuild for new comments to appear.

Live demo & GitHub repo

See the live demo here.

See GitHub repo here.

Closing thoughts

This demo took me about 1 - 2 hours, thanks to the Pelican documentation and Staticman’s simplicity.

I really enjoyed playing with Pelican! I had not worked with a static generator for a while and missed them. Docs were great and concise. The challenge was mostly with Python. I really didn’t write much of it, but I had never developed with Python before, so it was fun to try.

I would have liked to push the search further, at the moment it’s easy to use and setup but it wouldn’t be optimal for a lot of blog entries. The first thing I would do to scale this is outsource the search to something like Algolia. It would be much faster and way more powerful/scalable than what we have at the moment.

Happy coding!

If you’ve enjoyed this post, please take a second to share it on Twitter. Got comments, questions? Add them below!

I originally published this on the Snipcart blog and shared it in our newsletter.