Template hook is not being triggered in custom Nikola theme

Question

I am trying to write a custom theme for Nikola, a static site generator. I have been mostly following their tutorial but have run into a problem. I want to show certain HTML specifically on pages (not on posts) in the spot where the page_header template hook appears. So I first ran this command:

nikola theme -c page.tmpl

That copies the base theme's page.tmpl file into my custom theme's directory. That file is actually only 1 line long, simply this:

<%inherit file="story.tmpl"/>

So I added a definition for <%block name="page_header"> ... </%block>. However, the code I defined inside that block does not show up on my pages. Just to make sure I wasn't going crazy, I also defined <%block name="extra_head"> ... </%block> within that same page.tmpl file, and in that case the code contained therein did show up.

Why would the overridden extra_head block work while the overridden page_header block doesn't work within the same template file?

Answer 1

If you are having an issue where the overridden page_header block is not showing up but the extra_head block is, then it is possible that the page_header hook is not being used or triggered in the parent template (story.tmpl) that page.tmpl is inheriting from.

See zzzeek/mako / doc/build/inheritance.rst

Using template inheritance, two or more templates can organize themselves into an inheritance chain, where content and functions from all involved templates can be intermixed.
The general paradigm of template inheritance is this:

if a template A inherits from template B, then template A agrees to send the executional control to template B at runtime (A is called the inheriting template).
Template B, the inherited template, then makes decisions as to what resources from A shall be executed.

To check that, make sure that story.tmpl or any other template that it may inherit from actually uses the page_header block. If it does not exist there, then overriding it in page.tmpl will not have any effect.

Sometimes, there might be multiple layers of template inheritance. Do make sure there is no intermediate template between page.tmpl and story.tmpl that might be interfering with the blocks.

As a test, try to explicitly invoke the page_header block within page.tmpl outside of the block definition, like:

mako ${self.page_header()}

That should force the rendering of the content of that block, if it is correctly defined.