Welcome to kattni:decoded, and the new Intrinsic theme! I spent the last month working on designing a new theme for Pelican. A lot went into getting this site to a state that I am happy with. This post discusses the basic approach I took and the tools I chose.
I stated in a previous post that I chose a theme that sort of worked and tried to make it fit what I wanted and needed. In the end, it was less effort to basically start from scratch. I wanted to update the tools being used, which turned out to mean a complete overhaul. The initial theme had many features I had no intention of using, and much of the layout, which according to the author was the entire point, did not work for me. The author made it clear that any incoming changes would only be accepted if they fit within the current feel, and my changes were already significantly beyond that. So the option became to hang onto what little of that theme was left and continue to credit the original without being able to contribute back to it, or start over. I decided to start fresh and write my own theme.
Features
I made a mental list of some basic features I wanted out of my new theme, which included the following:
- Any software involved should be running the latest version, and should currently be actively maintained.
- The site should be usable on mobile.
- The navigation bar at the top should be simple and make the site easy to navigate.
- The main page should have the latest post, and a list of recent posts at the bottom.
- The footer should contain contact links, and info links relevant to the site.
- There should be a page with the list of all tags, and it should be searchable in some way. (I don't intend to use categories - I essentially use tags like some folks use categories.)
- There should be an archive of all the posts.
- Site search should be integrated.
The Latest Software
Now, when I say "latest", I mean latest. When I looked into Bootstrap, I noticed they had a beta release out, and decided to go that route. Here's hoping they use the term "beta" the same way I do, which is to say it's feature-complete, but they're still working on bug fixes. Their beta is quite stable in my experience. I didn't run into any issues, though I'm certain I'm not stretching the limitations of it.
Bootstrap
I chose to use Bootstrap for site layout. Bootstrap makes it easy to achieve clean, flexible, easy-to-style website layouts. The documentation is excellent. Note that I linked the 5.x documentation as that is the version I am using. If you would rather stick with a stable version, you should use the 4.x documentation. The docs provide clear examples for much of what you might consider doing with Bootstrap. I was able to pretty easily extrapolate from those examples in the instances where my goals were more complicated. I created a section in the theme CSS file that I titled Bootstrap Override to keep most of the Bootstrap-specific style changes delineated from the rest of the file. There are a few, such as the navbar, that are in their own sections. I tried not to override many of the Bootstrap defaults - I found that often if something wasn't quite right, there was probably another default option that did what I was trying to do. In some cases, Bootstrap tells you what to override. For example, with the navbar, there are a few default color options. They expect you to choose the one that creates the best basis for your intended palette, and indicate what to style to customise it to fit your site. My experience with Bootstrap was positive, and I would absolutely recommend it to anyone looking to theme a website.
Integrated Search
It turns out integrated search of a statically generated site is not a simple task. (That may be the reason why there are very few options available for Pelican, and the few available haven't been updated in many years.) I decided I wanted integrated search running something recent. There were a few options, and we opted to go with Lunr.js. The very, very short version is, it generates a file that contains the metadata and post data from my site, and searches that. The detailed version will require a lot of input from Rose, so I'll save that for another post. Basically, Rose wrote a new plugin for Pelican that we're calling Pelican Lunr. It's currently intertwined heavily with the theme. There are plugin files currently available on GitHub, but they won't work without files currently included in the Intrinsic theme. This is something we intend to change. The plan is to make it a standalone plugin and submit it to Pelican as such.
Tag Filtering
Filtering tags was relatively far simpler than integrated search. With so few tags at the moment, it seems like overkill. However, as I intend to use tags where others might use "categories", I felt the Tags page would quickly become unwieldy, and as such, unusable. You can click on a tag in a post and get the latest and other posts, or you can go to the Tags page and find a list of tags, and tag headers with applicable posts. This page has a search box at the top that filters both the tag list and the tag headers with applicable posts. You can also click on a tag in the list and it takes you to the tag header. Initially, I wanted the search to filter only the tag list, and then you could click on the tag to be taken to the header reference in the page. I hadn't considered anything beyond that because I had no idea how to do it. When Rose began working on this, she offered up the idea of including both. The more I thought about it, the more I felt that filtering both created a better user experience. You're presented with only the list of posts that matches the tag you are searching for. I'm happy with how it turned out.
Mobile Compatibility
The site now works on mobile, though I broke and fixed various related features a number of times throughout the update. Bootstrap makes it simple to design a site for multiple resolutions. This is another place where the Firefox Inspector comes into play. It allows you to easily view your site in common resolutions, and if desired, you can manually enter any resolution. This makes building and troubleshooting the mobile features much more straightforward from a desktop, versus needing to build and deploy the site and view it from a mobile device to find out if your latest update broke anything.
Final Thoughts
I can't thank (or apologise to) Rose enough for taking on the integrated search and tag filtering features. She spent time over several days working on them. My current impression of working with JavaScript is that it is like traversing a labyrinth full of dead ends, doors that go nowhere, and bottomless pits, much of which haven't been touched in ages, leaving a couple of decades worth of cobwebs and dust. However, I'll be the first to acknowledge I know essentially nothing about it personally, and I'll clarify that my impression is entirely based on watching Rose deal with it and listening to her frustrations. She's more vocal about her frustrations than she is about her successes. This endeavour turned out to be, in my opinion, a complete success. There are still updates to be made behind the scenes, as discussed elsewhere in this post, but the features work exactly as I wanted, including some options I hadn't even considered until Rose offered them as a concept. So while I have very little desire to begin working with JavaScript myself based on my experience of Rose's experience, I greatly appreciate the results of which it is capable.
I'm quite pleased with how the theme turned out. All the general features I outlined are included, as well as some I didn't know I could have until we began working on it. I'm sure I'll continue to make changes as I continue to work with the site and get new ideas. However, overall, we put together something I'm pretty happy with.
Note: I started this post ages ago, with the intention of posting it along with the theme update. I decided getting the theme updated was more important than posting about it, and I expected that I would have this post finished up a few days later, which did not happen. In the following weeks, Rose and I began working on a dark mode version of the theme, and Rose has also been working on extricating the Pelican Lunr plugin from the theme. These things meant that I managed to pretty thoroughly break the site building properly, which meant I couldn't post because it would have broken the site remotely as well. (This was my own fault for making changes on the main branch of the theme. I know better!) I only got around to fixing this today.