Questions about best practice for theming Nikola

[Damien Calloway]

I have been using Nikola for my blog for a while now, and would like to theme it in a certain way. I am having some problems grokking the theming tutorial and docs. I am getting tripped up over the use of Lanyon as a starting point - I agree it is a cool theme, but I am trying to pin down what needs to change and where (to get a certain result).

For now, I am using bootblog4 - I hard coded certain changes I wanted to make to the fonts, but I would like to know the more elegant way to change those details. And the layout, generally.

Is there another tutorial or resource besides : https://getnikola.com/creating-a-theme.html ?

I notice that the tutorial seems to suggest leaving the base HTML/CSS alone, and making the needed changes to the template files (.tmpl) - is that correct? If so, do these files have the same inheritance rules as CSS files?

Is this the same pattern that is encouraged for CSS files? Changes are put into <name_of_theme>.css? And conflicts with the base css are resolved by making the theme css file more specific?

If I understand correctly, baugettebox is what is used for the Gallery feature of Nikola?

[Chris Warrick]

On Sun, 19 Feb 2023 at 23:55, Damien Calloway <damienc...@gmail.com> wrote:
>
> I have been using Nikola for my blog for a while now, and would like to theme it in a certain way. I am having some problems grokking the theming tutorial and docs. I am getting tripped up over the use of Lanyon as a starting point - I agree it is a cool theme, but I am trying to pin down what needs to change and where (to get a certain result).
>
> For now, I am using bootblog4 - I hard coded certain changes I wanted to make to the fonts, but I would like to know the more elegant way to change those details. And the layout, generally.
>
> Is there another tutorial or resource besides : https://getnikola.com/creating-a-theme.html ?

We have two more resources:

* https://getnikola.com/theming.html — which is a reference about how
themes work in general
* https://getnikola.com/template-variables.html — which is a list of
variables available in templates

> I notice that the tutorial seems to suggest leaving the base HTML/CSS alone, and making the needed changes to the template files (.tmpl) - is that correct? If so, do these files have the same inheritance rules as CSS files?
>
> Is this the same pattern that is encouraged for CSS files? Changes are put into <name_of_theme>.css? And conflicts with the base css are resolved by making the theme css file more specific?

Every theme should inherit from some other theme. The most basic
themes are `base` (for Mako) and `base-jinja` (for Jinja2). You can
also build on top of any other theme you like (e.g. the
bootstrap/bootblog families).

CSS-wise, the base themes come with a `theme.css` that gives a simple
yet stylish appearance, but you can replace it with your own file, or
you can add a `custom.css` with your own rules. In the bootstrap
themes, bootstrap stuff lives in `bootstrap.min.css`, and some custom
Nikola things (that may override Bootstrap stuff) are in `theme.css`.
Not all themes out there may respect `custom.css` though.

HTML-wise, the base themes come with a complete set of templates. You
can override a template, but if you do, you must include everything
that was in the parent template (unless it’s no longer relevant to
your site). Templates support inheritance, so e.g. in bootblog4, some
templates come from bootblog4 (those that need to add extra HTML or
CSS to use the bootblog features), some are from bootstrap4, and some
are from base (especially the generic/rarely styled things, like
comments).

The `nikola theme` command has a few options that can help create a
theme or copy templates from the parent into your current theme (or
into your site, if you don’t have a custom theme).

> If I understand correctly, baugettebox is what is used for the Gallery feature of Nikola?

Yes, although you can use something else, Nikola does not mandate
using anything here.

--
Chris Warrick <https://chriswarrick.com/>
PGP: 5EAAEA16

[Damien Calloway]

Hello, and thank you for the reply, and for the additional explanations. It appears that I do need to spend some more time with this... I do have some further questions after reviewing those links, though.

I want to take the parts of bootblog4 that I like, and add a few other items - I am thinking about using base-jinja to build a new theme from, using Bootstrap 5 and possibly parts of the docutils css. I want to use the image gallery in Bootstrap 5, such that I do not have any other external JS dependencies (Bootstrap 5 itself dropped jQuery). I believe this will have a cleaner, more maintainable structure.

If I understand correctly, I could use base-jinja as the parent for a theme that uses Jinja theme engine, then tweak the CSS to dial in the look that I want?

Also, is there a compelling reason to use the existing bootstrap themes as a parent if I wanted a cleaner Bootstrap 5 integration? I ask, because I showed my blog's CSS to a Bootstrap dev who did not recognize certain elements the bootblog4 theme used on my site. It made pinning down the location for certain changes take longer than expected. As I examine some of the CSS and theme styling in the existing Bootblog4 I see references to manual tweaks and issues that I do not totally get. I cannot tell if those changes were made to get the look that they wanted (aesthetics) or to get the functionality they wanted (i.e., just getting it to work).

Finally, what advantage would there be to using a "subtheme"?

Thank you again for your help.

[Chris Warrick]

On Tue, 21 Feb 2023 at 02:26, Damien Calloway <damienc...@gmail.com> wrote:
>
> Hello, and thank you for the reply, and for the additional explanations. It appears that I do need to spend some more time with this... I do have some further questions after reviewing those links, though.
>
> I want to take the parts of bootblog4 that I like, and add a few other items - I am thinking about using base-jinja to build a new theme from, using Bootstrap 5 and possibly parts of the docutils css. I want to use the image gallery in Bootstrap 5, such that I do not have any other external JS dependencies (Bootstrap 5 itself dropped jQuery). I believe this will have a cleaner, more maintainable structure.

The bootstrap themes are quite small themselves, but you can do that.

> If I understand correctly, I could use base-jinja as the parent for a theme that uses Jinja theme engine, then tweak the CSS to dial in the look that I want?

Sure.

> Also, is there a compelling reason to use the existing bootstrap themes as a parent if I wanted a cleaner Bootstrap 5 integration? I ask, because I showed my blog's CSS to a Bootstrap dev who did not recognize certain elements the bootblog4 theme used on my site. It made pinning down the location for certain changes take longer than expected. As I examine some of the CSS and theme styling in the existing Bootblog4 I see references to manual tweaks and issues that I do not totally get. I cannot tell if those changes were made to get the look that they wanted (aesthetics) or to get the functionality they wanted (i.e., just getting it to work).

It really depends, we cannot answer this question, since the
distinction between aesthetics vs functionality is lost to history.
The themes are based on Bootstrap, but they do have some custom things
— but all of them live outside of bootstrap.min.css, so they should
not be that difficult to find.

> Finally, what advantage would there be to using a "subtheme"?

Subthemes are there so you can easily use a third-party service that
offers an alternate bootstrap-compatible CSS. They are not useful for
anything else.