-
Notifications
You must be signed in to change notification settings - Fork 456
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Template improvements #3760
base: master
Are you sure you want to change the base?
Template improvements #3760
Changes from all commits
dea03ac
3fef32a
8828557
817c5c4
3b68cab
3545a71
46faec9
2742c99
04a47db
a319b4b
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
@@ -7,7 +7,7 @@ | |||||||||||
.. author: The Nikola Team | ||||||||||||
|
||||||||||||
:Version: 8.3.1 | ||||||||||||
:Author: Roberto Alsina <[email protected]> | ||||||||||||
:Author: Roberto Alsina <[email protected]> and others | ||||||||||||
|
||||||||||||
.. class:: alert alert-primary float-md-right | ||||||||||||
|
||||||||||||
|
@@ -130,8 +130,17 @@ The following keys are currently supported: | |||||||||||
|
||||||||||||
The parent is so you don’t have to create a full theme each time: just | ||||||||||||
create an empty theme, set the parent, and add the bits you want modified. | ||||||||||||
You **must** define a parent, otherwise many features won’t work due to | ||||||||||||
missing templates, messages, and assets. | ||||||||||||
|
||||||||||||
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.) | ||||||||||||
|
||||||||||||
The following settings are recommended: | ||||||||||||
|
||||||||||||
|
@@ -184,8 +193,16 @@ so ``post.tmpl`` only define the content, and the layout is inherited from ``bas | |||||||||||
|
||||||||||||
Another concept is theme inheritance. You do not need to duplicate all the | ||||||||||||
default templates in your theme — you can just override the ones you want | ||||||||||||
changed, and the rest will come from the parent theme. (Every theme needs a | ||||||||||||
parent.) | ||||||||||||
changed, and the rest will come from the parent theme. If your theme does not | ||||||||||||
define a parent, it needs to be complete. It is generally a lot harder to | ||||||||||||
come up with a complete theme, compared to only changing a few files and using | ||||||||||||
the rest from a suitable parent theme. | ||||||||||||
|
||||||||||||
.. Tip:: | ||||||||||||
|
||||||||||||
If you set the environment variable ``NIKOLA_TEMPLATES_TRACE`` to any non-empty value | ||||||||||||
(``true`` is recommended), Nikola will log template usage, both on output and also | ||||||||||||
into a file ``templates_log.txt``. | ||||||||||||
Comment on lines
+203
to
+205
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Unnecessary detail.
Suggested change
|
||||||||||||
|
||||||||||||
Apart from the `built-in templates`_ listed below, you can add other templates for specific | ||||||||||||
pages, which the user can then use in his ``POSTS`` or ``PAGES`` option in | ||||||||||||
|
@@ -194,11 +211,11 @@ page via the ``template`` metadata, and custom templates can be added in the | |||||||||||
``templates/`` folder of your site. | ||||||||||||
|
||||||||||||
If you want to modify (override) a built-in template, use ``nikola theme -c | ||||||||||||
<name>.tmpl``. This command will copy the specified template file to the | ||||||||||||
``templates/`` directory of your currently used theme. | ||||||||||||
<name>.tmpl``. This command will copy the specified template file from the | ||||||||||||
parent theme to the ``templates/`` directory of your currently used theme. | ||||||||||||
|
||||||||||||
Keep in mind that your theme is *yours*, so you can require whatever data you | ||||||||||||
want (eg. you may depend on specific custom ``GLOBAL_CONTEXT`` variables, or | ||||||||||||
want (e.g., you may depend on specific custom ``GLOBAL_CONTEXT`` variables, or | ||||||||||||
post meta attributes). You don’t need to keep the same theme structure as the | ||||||||||||
default themes do (although many of those names are hardcoded). Inheriting from | ||||||||||||
at least ``base`` (or ``base-jinja``) is heavily recommended, but not strictly | ||||||||||||
|
@@ -475,6 +492,28 @@ at https://www.transifex.com/projects/p/nikola/ | |||||||||||
If you want to create a theme that has new strings, and you want those strings to be translatable, | ||||||||||||
then your theme will need a custom ``messages`` folder. | ||||||||||||
|
||||||||||||
Configuration of the raw template engine | ||||||||||||
---------------------------------------- | ||||||||||||
|
||||||||||||
For usage not covered by the above, you can define a method | ||||||||||||
`TEMPLATE_ENGINE_FACTORY` in `conf.py` that constructs the raw | ||||||||||||
underlying templating engine. That `raw_engine` that your method | ||||||||||||
needs to return is either a `jinja2.Environment` or a | ||||||||||||
`mako.loopkup.TemplateLookup` object. Your factory method is | ||||||||||||
called with the same arguments as is the pertinent `__init__`. | ||||||||||||
|
||||||||||||
E.g., to configure `jinja2` to bark and error out on missing values, | ||||||||||||
instead of silently continuing with empty content, you might do this: | ||||||||||||
|
||||||||||||
.. code:: python | ||||||||||||
|
||||||||||||
# Somewhere in conf.py: | ||||||||||||
def TEMPLATE_ENGINE_FACTORY(**args) -> jinja2.Environment: | ||||||||||||
augmented_args = dict(args) | ||||||||||||
augmented_args['undefined'] = jinja2.DebugUndefined | ||||||||||||
return jinja2.Environment(**augmented_args) | ||||||||||||
|
||||||||||||
|
||||||||||||
`LESS <http://lesscss.org/>`__ and `Sass <https://sass-lang.com/>`__ | ||||||||||||
-------------------------------------------------------------------- | ||||||||||||
|
||||||||||||
|
Original file line number | Diff line number | Diff line change | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
@@ -29,8 +29,19 @@ | |||||||||||||
import os | ||||||||||||||
import sys | ||||||||||||||
|
||||||||||||||
# The current Nikola version: | ||||||||||||||
__version__ = '8.3.1' | ||||||||||||||
|
||||||||||||||
# A flag whether logging should emit debug information: | ||||||||||||||
DEBUG = bool(os.getenv('NIKOLA_DEBUG')) | ||||||||||||||
|
||||||||||||||
# A flag whether special templates trace logging should be generated: | ||||||||||||||
aknrdureegaesr marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||
TEMPLATES_TRACE = bool(os.getenv('NIKOLA_TEMPLATES_TRACE')) | ||||||||||||||
|
||||||||||||||
# When this flag is set, fewer exceptions are handled internally; | ||||||||||||||
# instead they are left unhandled for the run time system to deal with them, | ||||||||||||||
# which typically leads to the stack traces being exposed. | ||||||||||||||
Comment on lines
+41
to
+43
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
( There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The wording "of unhandled exceptions" suggests whether the exceptions is handled or not is independent of this setting. As far as I remember, this is not the case. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Technically, all exceptions are handled. This setting affects exceptions that bubble up to the global handler and therefore crash the process. |
||||||||||||||
# This is a less noisy alternative to the NIKOLA_DEBUG flag. | ||||||||||||||
SHOW_TRACEBACKS = bool(os.getenv('NIKOLA_SHOW_TRACEBACKS')) | ||||||||||||||
|
||||||||||||||
if sys.version_info[0] == 2: | ||||||||||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again, unsupported and should not be documented.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What do you think about the compromise "we document that this is unsupported", which is what I'm trying to do here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I’m still not a fan of documenting it at all, but I guess it can stay as-is.