I adjusted the default Nikola theme to show cover images!
The now page, in Nikola
I am a visual person. You might not know that from all the typing and my enthusiasm for command line tools. But many of my posts and pages have cover images. Sometimes the cover images are even relevant to the post.
In the live site, cover images are prominently displayed at the top of their pages. They get referenced when a post gets shared on social media. A cropped and adjusted version of the cover image gets displayed in post summaries.
So if I’m using Nikola to build something like my current site, I need cover images.
Nikola site uses the bootblog4 theme by default, taking advantage of the Bootstrap toolkit. bootblog4 doesn’t support cover images, so I’ll make a version that does.
Mind you, I don’t want to build a whole new theme. That can come later. There’s even a nice tutorial for creating a theme. For now I just want to tweak the default a little.
Set up files and metadata
Nikola starts with a few assumptions I can work with. bootblog4 already looks for
previewimage metadata to build thumbnails for featured posts. Nikola also expects to find image files in your site’s
images/ folder. Makes sense.
I’ll mirror the content path with images, and add
previewimage metadata which points to the right spot.
I prefer how Hugo handles page bundles. Everything for your content is in the same folder. Many other static site generators — including Nikola — keep supplemental content separate from posts.
Hugo uses a powerful but sometimes confusing taxonomy system in layout customization. Nikola prefers a powerful but sometimes confusing “theme inheritance” system. Look. They’re all confusing. It’s just a matter of finding the kind of confusing you don’t mind.
With theme inheritance, my tweaks are a new theme. But the new theme basically says “I’m like that theme, except that I changed these templates.”
So let’s inherit a theme.
-i ARG, --install=ARG
|Install a theme. (config: install)
-r ARG, --uninstall=ARG
|Uninstall a theme. (config: uninstall)
|Show list of available themes. (config: list)
|List the installed themes with their location. (config: list_installed)
-u ARG, --url=ARG
|URL for the theme repository (default: https://themes.getnikola.com/v8/themes.json) (config: url)
-g ARG, --get-path=ARG
|Print the path for installed theme (config: getpath)
-c ARG, --copy-template=ARG
|Copy a built-in template into templates/ or your theme (config: copy-template)
-n ARG, --new=ARG
|Create a new theme (config: new)
|Engine to use for new theme (mako or jinja – default: mako) (config: new_engine)
|Parent to use for new theme (default: base) (config: new_parent)
|Create legacy meta files for new theme (config: new_legacy_meta)
So I ask Nikola for a new theme, using bootblog4 as the parent.
Because I didn’t specify a template engine, rgb-bootblog4 uses Mako.
Let’s remember to update
conf.py as directed, so we can see the theme as we tweak it. The theme tutorial also mentions disabling
Sweet. I have a new
themes/rgb-bootblog4 folder. Wait. It has no templates.
Oh that’s right. This is what they were talking about with template inheritance. The templates are still in the parent. It’s up to me to copy and change specific templates. That’s both good and a little risky when the parent theme updates. What if my tweak turns out to be incompatible? Okay, not going to worry about it today. If you’re going to veer wildly from the parent, you should probably use base as the parent.
The Mako extension for Visual Studio Code associates itself with
.makofiles. You can add
.tmplto that with the
files.associationssetting. Might not want to do that globally though.
.tmplcould be Mako here, but Jinja2 in another site.
Instead, change it in the workspace file for your Nikola site.
So which of the built-in templates do I want? Since both posts and pages have cover images on my site, I’ll start with the most general template. Everything starts with
base.tmpl. Let’s look there.
Can I find anything interesting in the base template?
Over here on the live site, I put cover images above the main content.
extra_header looks promising. Where to set it? I prefer to make my changes in the most relevant template instead of the most general.
Give me a minute to explore…
Okay. Pages ultimately inherit from posts — Mako supports template inheritance, letting the parent define some blocks while overriding others. We might be able to do this with one change.
Nikola provides a large number of template variables to work with, but today I focus on
post. How about the preview image? It gets set in post metadata, so I could use
post.meta("previewimage"). Don’t have to do that though.
previewimage metadata is important enough that it gets promoted to an attribute of the post object.
Keep in mind what I noticed the other dayabout these not being real figures in reStructuredText. For now I match RST output, as if I’d used a figure directive. That way I don’t have to find the CSS for this theme.
It has a cover image, placed right by the title. It doesn’t quite match today’s view of that post, but this has the basic idea. And I only had to edit a single template file!
Looks good for posts that have a cover image. How about pages?
Excellent. I thought that would take much more work.
bootblog4 is based off of Bootstrap. I feel compelled to make the cover image a Jumbotron.
Hm. Maybe, maybe not. I’m tempted to tweak it some more, but my task list is long and my time is short.
Did I miss anything?
Sort of. On the live site, I let Hugo resize cover images to fit in my design and avoid large downloads. Nikola has thumbnails, but that’s not quite the same thing. I’d have to do it myself, maybe with a plugin.
Added to vault 2024-01-15. Updated on 2024-02-02