Modifying a Nikola theme

posts/misc/modifying-a-nikola-theme.org

@@ -0,0 +1,71 @@
+#+BEGIN_COMMENT
+.. title: Modifying a /Nikola/ theme
+.. date: 2020-09-01 20:00
+.. slug: modifying-a-nikola-theme
+.. updated: 2020-09-01 20:00
+.. status: published
+.. tags: nikola, theme
+.. category: misc
+.. authors: Elia el Lazkani
+.. description: I needed to make a few changes to the theme I am using for my blog with /Nikola/. Here's how to do it.
+.. type: text
+#+END_COMMENT
+
+After publishing my /blog/ in new form yesterday night, I have received some suggestions for changes to the theme.
+
+First off, I noticed that the footer is not showing after the blog was deployed. That reminded me that I have made changes to the original theme on disk. The pipeline, though, install the theme fresh before deploying the website.
+
+I needed to fix that. Here's how I did it.
+
+{{{TEASER_END}}}
+
+* Create a new theme
+This might be counter intuitive but /themes/ in /Nikola/ can actually have parents. So what we need to do is clone the theme we want to modify while keeping it as parent to our theme. I'll show you.
+
+First, create your new theme.
+
+#+BEGIN_EXAMPLE
+$ nikola theme --new custom-willy-theme --parent willy-theme --engine=jinja
+#+END_EXAMPLE
+
+#+BEGIN_EXPORT html
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+#+END_EXPORT
+I had to use =--engine=jinja= because /willy-theme/ uses jinja templating. If you are using the /mako/ engine, you don't need to add thihs as the *default* is /mako/.
+#+BEGIN_EXPORT html
+</div>
+#+END_EXPORT
+
+#+BEGIN_EXPORT html
+<div class="admonition warning">
+<p class="admonition-title">warning</p>
+#+END_EXPORT
+You will /probably/ need both themes in your =themes/= directory. The /willy-theme/ needs to be installed before creating your /custom/ theme from it.
+#+BEGIN_EXPORT html
+</div>
+#+END_EXPORT
+
+
+This should create =themes/custom-willy-theme/=. If we look inside, we'll see one file that describes this /theme/ with its *parent*.
+
+Go to your =conf.py= and change the /theme/ to =custom-willy-theme=.
+
+* Let's talk hierarchy
+Now that we have our own /custom theme/ out of the /willy-theme/, if we rebuild the blog we can see that nothing changes. Of course, we have not made any modifications. But did you ever ask yourself the question, why did the site not change ?
+
+If your theme points to a *parent*, whatever /Nikola/ expects will have to be *your theme first* with a *failover to the parent* theme. Ok, if you've followed so far, you will need to know what /Nikola/ is expecting right ?
+
+You can dig into the /documentation/ here to find out what you can do, but I wanted to change a few things to the theme. I wanted to add a footer, for example.
+
+It turns out for /willy-theme/ that is located in the =templates/base.tmpl=. All I did was the following
+
+#+BEGIN_EXAMPLE
+$ mkdir themes/custom-willy-theme/templates
+$ cp themes/willy-theme/templates/base.tmpl themes/custom-willy-theme/templates/
+#+END_EXAMPLE
+
+I made my modification to the =base.tmpl= and rendered the blog. It was that simple. My changes were made.
+
+* Conclusion
+You can always clone the /theme repository/ and make your modifications to it. But maintenance becomes an issue. This seems to be a cleaner way for me to make modifications on the original /theme/ I'm using. This is how you can too.