In this post, I discuss the issues I ran into while setting up this site, the solutions I came up with, and some suggestions based on my experience. This site was built using Pelican. I won't be discussing how I set up this site, only the issues I encountered. I recommend reading the previous post as it covers my workflow, which should give context to the following.


The most persistent issue I ran into was permissions related. Every time I would make rsync_upload the site, it would reset the permissions and my site or portions of it would come up with a 403: Forbidden error. I ended up modifying the rsync command in the Makefile to include -a which is archive, which sets a bunch of flags. This workaround solved the problem, but it didn't address the underlying issue. It turns out the real issue was that my umask was being modified in my .bashrc file. Once I managed to get that sorted, I was able to remove the -a from rsync in the Makefile and so far it seems to be working fine.

Choosing a Theme

The Pelican Themes site shows screenshots of all the themes that provided screenshots, and lists the rest at the bottom. I found it a bit overwhelming - there's no way to filter or search other than by name. I ended up going through the list with a text document open, and listing the ones I thought I might be interested in, and then narrowing it down from there. I initially only considered themes with screenshots (for obvious reasons), but ended up choosing a theme that did not. I would suggest clicking through the link list at the bottom of the page, as some of the themes had demo sites linked from the theme repo. However, many did not, and I ended up passing those up by default. Remember, to test a theme, download it to the themes folder, enable it in, and generate the site. I did not have the desire to download all the themes without demos to check them out, but the option is there, should you choose to do it.

As I mentioned in my initial Let's Talk Pelican post, I spent significantly more time tweaking the theme than I did setting up the site or writing my initial content. I couldn't find a theme that looked like what I wanted and had the features I wanted. The thing that led me to the theme I ended up choosing was looking into the search plugin, and the plugin indicated this theme as one that used it. It linked to the demo site (which is also the documentation for the theme). I liked the overall feel well enough, but it still didn't have the features I wanted. Instead of continuing to dig through themes, I decided to try to make this theme work. The theme I ended up starting with was designed for a static landing page with some links on it, and links to recent posts. I wanted to display the latest post along with the list of recent posts. It took me longer than I care to admit to get that sorted out, and required a bit of assistance along the way. It still has some quirks, but does what I want for the most part now. I'm still working through enabling other features of the theme and getting them in line with my overall feel.

All of that said, I don't recommend trying to battle a theme to get going. Most sites I set up previously, I was blocked on writing my first post. In this case, that was done quickly, and trying to get the theme working is what ended up taking the most time. If you're simply looking to spin up a site, find a theme that works for you, and go with it. However, if you're looking for Adventures in Jinja Templating and CSS, then follow my lead into the breach.

Editing CSS

This isn't so much a problem I ran into, as much as it is a tip that will save you an unbelievable amount of time if you're attempting to modify an existing theme. In Firefox (and presumably similar in other browsers as well), when hovering over part of a website's content, there is an option in the right-click menu to "Inspect Element". This opens the Inspector. (You can apparently also open it from the Tools menu under Web Development.) There are excellent docs explaining how everything works in this, but the key takeaway is that you can see what CSS is being applied to a particular element, and edit it live to see what affects it has. This easily saved me hours of modifying random divs hoping to change the intended element. I highly recommend using this feature if you are planning to do any theme modifications to your site.

As a side note, the theme I chose had an empty custom.css file available that takes precedence over the theme's default CSS file. This makes it easier to deal with upgrading the theme later if you choose to because you aren't modifying theme-specific files. I assume other themes may have similar, and I suggest using it if it's available. It also means not digging through the existing CSS file to find what you're looking for, and instead simply adding it to custom.css. Paired with the Inspector in Firefox, it made modifying the theme much simpler than it might otherwise have been.

In my case, in terms of updating in the future, I modified the theme files heavily enough that I forked the repo and renamed it. I'm working on updating significant parts of it, and once that's complete, I will likely break off of it being based on that theme at all. At that point, I'll submit the theme as a new theme to Pelican, and I'll write something up on that process.

Pelican vs Make

As I initially went through getting the site set up, I followed the docs in basically the order in which they were written. They follow a reasonable order to get you through the initial steps to the point of publishing your site. When I reached the Publish your site section, I used the pelican commands as provided. Initially, the site wasn't rendered with the theme, and I had to dig further into the docs to find the Creating themes section which explained running pelican -t. So, to render it with the theme, you must first run it with -t and then run pelican --autoreload --listen to begin to edit the theme. It didn't occur to me to read further into the Publish docs. Eventually, as I was going in circles attempting to edit the theme, my friend pointed me to make devserver.

The make devserver command essentially runs all the above together, and creates a web server you can view at http://localhost:8000/. It renders the site with the theme, and recognises any changes you make to the theme as you make them. This command made the pelican commands feel incredibly convoluted. It wasn't something I felt initially because I didn't know there was another option, but once I found make devserver, the pelican method seemed like a massive waste of time. I may not have been using them as intended, and there may be a more streamlined way of using the pelican command method, but it was not readily clear to me from the documentation. This is why I highly recommend allowing pelican-quickstart to create the Makefile. It became the majority of my workflow.

There are times it would not render changes I made or when I wasn't certain it was rendering changes I made, and at that point, I hit CTRL + c to stop it, and ran make clean to wipe the current output directory and begin again. make clean resets everything to a known state. You should run make clean when you feel like you're going in circles making changes to your site, or when you want to test a new theme, or if you simply need a baseline. The going in circles thing is crucial. I tend to assume whatever I'm dealing with is a me-problem, but in the case of battling with the theme I chose, it turned out much of it wasn't me-related, and it was simply due to things not updating properly. make clean can be as much your friend as make devserver.

Clean URLs

This theme, and others, support what's referred to as "clean URLs". This refers to removing the ".html" from the URL, so you can navigate to a page using versus it showing up in the address bar as (which should also work regardless of the clean URL settings). The documentation for the theme explains how to enable clean URLs, and includes a warning saying something to the effect of, "Your server must support clean URLs," with no indication whatsoever as to what that involves. Enter good ol' .htaccess.

Before this, my knowledge of the .htaccess file was necessary for Wordpress, always had permissions issues, and when things weren't rendering right, it was almost always the fault of that file. Well, it turns out it has other uses as well. In this case, it uses regex to make the clean URLs work. There are multiple ways to do this, as per StackOverflow, and the multiple permutations mine went through while I was fighting permissions issues (and not realising that was the issue). Here are the current contents of my .htaccess file.

RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME}\.html -f
RewriteRule ^(.*)$ $1.html [NC,L]
ErrorDocument 404 /404.html

It works with this theme to enable clean URLs (as well as enabling the custom 404 page). I make no guarantees whether it'll work as-is for you.

Check Your Slugs!

This was a perplexing issue with a face palm solution. I finally sorted out the permissions issues and thought I had a viable .htaccess file in place, but for some reason, the About page on my site was still showing up as in the address bar. After fighting with the file, the .htaccess file, and every other possible angle I could think of, I was about to dig into the source code to figure out what page.url rendered. For some unknown reason, I decided to check the file itself. The slug was about/index. Facepalm.

Slugs will get you every time. If the URL seems weird and something doesn't make sense, the first thing you should check is what you entered as the slug for the page or post. It's basically the simplest thing you can check, and you'll eliminate that as a possible cause.

Final Thoughts

This covers the major things I feel would have made for a smoother experience had I known from the beginning. If I remember anything further, I'll share it in another post. I'm certain others' experiences will differ from mine, and it's likely the set of issues encountered won't line up exactly with these. On the off chance they do, it is my hope that this post will help alleviate the frustration I experienced and provide possible solutions.

Setting up a site using Pelican was not a simple task, at least for me. The satisfaction I got out of managing to get everything working, and the fact that I can now write content using Markdown, made it worth it. That I don't have to deal with Wordpress in my personal time is icing on the cake. I'm not done theming, so my frustrations are far from over. This is how I choose to spend my time.

The thing to remember is, once you get a theme you're happy with, there's very little of the above that you'll need to deal with. You can simply add your content and deploy. Hopefully this set of posts makes getting to that point a little simpler for you.