Nikola is certainly a good static pages generator, but the documentation is really pitiful!

[Thierry-3D]

For several days I'm struggling to create a static blog via Nikola, with a well-written html5 structure (which is not the case of the default theme) and some clean scss stylesheet (which never compile for now…)

Nikola's documentation is so sparse and confusing that, despite being 30 years in full-stack development, my project became a game of trial and errors, trying to guess the location and format of many, many files.

Could you, at least, provide a tutorials explaining every step, every needed files (and their format), to get rid of the horrible default theme and write a theme from scratch?

[aknrdureegaesr]

I'm just a random Nikola contributor who has happened to provide a somewhat pertinent pull request recently. What I write is not an official answer by the Nikola team.

Some functionality

That pull request introduces a new environment variable. To quote the online documentation:

If you set the environment variable NIKOLA_TEMPLATES_TRACE to true, Nikola will log template usage, both to output and also into a file templates_log.txt.

This will be available with the next release. For now, you can have this if you install from source.

Templates from scratch?

There was some discussion about this in the context of my pull request. Management summary:

On the plus side: Some people use and others want "templates from scratch". The second group includes myself. I myself don't have that up and running yet, but want to work on it "soon", for some as-of-yet undetermined value of "soon".

But at least one Nikola core developer is afraid officially supporting "template from scratch" will result in many tickets in that field.

So another stance in the upcoming next version's documentation will read:

While it is possible to create a theme without a parent, it is strongly discouraged and not officially supported, in the sense: We won't help with issues that are caused by a theme being parentless, and we won't guarantee that it will always work with new Nikola versions. The base and base-jinja themes provide assets, messages, and generic templates that Nikola expects to be able to use in all sites. That said, if you are making something very custom, Nikola will not prevent the creation of a theme without base, but you will need to manually determine which templates and messages are required in your theme. (Initially setting the NIKOLA_TEMPLATES_TRACE environment variable might be of some help, see below.)

Documentation improvement

In my own humble opinion, the structure of the templates is not sufficiently documented. I agree to that. On the other hand, from what I've seen thus far, I didn't find it chaotic or surprising.

Just in case you want to help to improve the documentation in that arena, feel free to come up with a pull request yourself. I would be surprised if the team would not accept it.

How does the documentation work, technically? I took this discussion as an opportunity to create a new feature request #3822 and (somewhat) document there how to locally render the Nikola documentation.