-
Notifications
You must be signed in to change notification settings - Fork 448
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
b268469
fc7a75f
893e4c0
074f59d
b46b121
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.0 | ||
:Author: Roberto Alsina <[email protected]> | ||
:Author: Roberto Alsina <[email protected]> and others | ||
|
||
.. class:: alert alert-primary float-md-right | ||
|
||
|
@@ -104,8 +104,8 @@ with the same name as your theme, and a ``.theme`` extension, eg. | |
.. code:: ini | ||
|
||
[Theme] | ||
engine = mako | ||
parent = base | ||
engine = jinja | ||
parent = base-jinja | ||
author = The Nikola Contributors | ||
author_url = https://getnikola.com/ | ||
based_on = Bootstrap 3 <https://getbootstrap.com/> | ||
|
@@ -120,6 +120,10 @@ with the same name as your theme, and a ``.theme`` extension, eg. | |
[Nikola] | ||
bootswatch = True | ||
|
||
[jinja] | ||
# Good for investigation, but not recommended to leave active in production: | ||
extensions = jinja2.ext.debug | ||
|
||
The following keys are currently supported: | ||
|
||
* ``Theme`` — contains information about the theme. | ||
|
@@ -130,8 +134,9 @@ 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. | ||
It is strongly recommended you define a parent. If you don't, many features | ||
won’t work due to missing templates, messages, and assets until your home-grown | ||
template is complete. | ||
|
||
The following settings are recommended: | ||
|
||
|
@@ -163,6 +168,13 @@ The following keys are currently supported: | |
* ``ignored_assets`` — comma-separated list of assets to ignore (relative to | ||
the ``assets/`` directory, eg. ``css/theme.css``) | ||
|
||
* ``jinja`` - This section is ignored unless your theme's engine is ``jinja``. | ||
|
||
* ``extensions`` - comma-separated list of | ||
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. I’m OK with this, but perhaps it would be more useful to do this in 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. I first thought the opportune place for template configuration is the theme configuration file. It is there I tell Nikola which engine to use in the first place. On the other hand, So I'll agree doing something like this in |
||
`jinja2-extensions <https://jinja.palletsprojects.com/en/3.1.x/extensions/>`_ | ||
that you want to be available when rendering your templates. | ||
|
||
|
||
Templates | ||
--------- | ||
|
||
|
@@ -184,8 +196,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 | ||
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. Again, unsupported and should not be documented. |
||
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``. | ||
|
||
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 +214,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 | ||
|
Original file line number | Diff line number | Diff line change | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
@@ -29,8 +29,15 @@ | |||||||||||||
import os | ||||||||||||||
import sys | ||||||||||||||
|
||||||||||||||
# The current Nikola version: | ||||||||||||||
__version__ = '8.3.0' | ||||||||||||||
# A flag whether logging should emmit debug information: | ||||||||||||||
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
|
||||||||||||||
DEBUG = bool(os.getenv('NIKOLA_DEBUG')) | ||||||||||||||
# A flag whether special templates trace logging should be generated: | ||||||||||||||
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
|
||||||||||||||
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
+38
to
+40
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
( |
||||||||||||||
SHOW_TRACEBACKS = bool(os.getenv('NIKOLA_SHOW_TRACEBACKS')) | ||||||||||||||
|
||||||||||||||
if sys.version_info[0] == 2: | ||||||||||||||
|
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -30,7 +30,7 @@ | |||||
import logging | ||||||
import warnings | ||||||
|
||||||
from nikola import DEBUG | ||||||
from nikola import DEBUG, TEMPLATES_TRACE | ||||||
|
||||||
__all__ = ( | ||||||
"get_logger", | ||||||
|
@@ -86,6 +86,10 @@ class LoggingMode(enum.Enum): | |||||
QUIET = 2 | ||||||
|
||||||
|
||||||
_LOGGING_FMT = "[%(asctime)s] %(levelname)s: %(name)s: %(message)s" | ||||||
_LOGGING_DATEFMT = "%Y-%m-%d %H:%M:%S" | ||||||
|
||||||
|
||||||
def configure_logging(logging_mode: LoggingMode = LoggingMode.NORMAL) -> None: | ||||||
"""Configure logging for Nikola. | ||||||
|
||||||
|
@@ -101,12 +105,7 @@ def configure_logging(logging_mode: LoggingMode = LoggingMode.NORMAL) -> None: | |||||
return | ||||||
|
||||||
handler = logging.StreamHandler() | ||||||
handler.setFormatter( | ||||||
ColorfulFormatter( | ||||||
fmt="[%(asctime)s] %(levelname)s: %(name)s: %(message)s", | ||||||
datefmt="%Y-%m-%d %H:%M:%S", | ||||||
) | ||||||
) | ||||||
handler.setFormatter(ColorfulFormatter(fmt=_LOGGING_FMT, datefmt=_LOGGING_DATEFMT)) | ||||||
|
||||||
handlers = [handler] | ||||||
if logging_mode == LoggingMode.STRICT: | ||||||
|
@@ -137,6 +136,39 @@ def get_logger(name: str, handlers=None) -> logging.Logger: | |||||
|
||||||
|
||||||
LOGGER = get_logger("Nikola") | ||||||
TEMPLATES_LOGGER = get_logger("nikola.templates") | ||||||
|
||||||
|
||||||
def init_template_trace_logging(filename: str) -> None: | ||||||
"""Initialize the tracing of the template system. | ||||||
|
||||||
This tells a theme designer which templates are being exercised | ||||||
and for which output files, and, if applicable, input files. | ||||||
|
||||||
As there is lots of other stuff happening on the normal output stream, | ||||||
this info is also written to a log file. | ||||||
""" | ||||||
TEMPLATES_LOGGER.level = logging.DEBUG | ||||||
formatter = logging.Formatter( | ||||||
fmt=_LOGGING_FMT, | ||||||
datefmt=_LOGGING_DATEFMT, | ||||||
) | ||||||
shandler = logging.StreamHandler() | ||||||
shandler.setFormatter(formatter) | ||||||
shandler.setLevel(logging.DEBUG) | ||||||
|
||||||
fhandler = logging.FileHandler(filename, encoding="UTF-8") | ||||||
fhandler.setFormatter(formatter) | ||||||
fhandler.setLevel(logging.DEBUG) | ||||||
|
||||||
TEMPLATES_LOGGER.handlers = [shandler, fhandler] | ||||||
TEMPLATES_LOGGER.propagate = False | ||||||
|
||||||
TEMPLATES_LOGGER.info("Template usage being traced to file %s", filename) | ||||||
|
||||||
|
||||||
if TEMPLATES_TRACE: | ||||||
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. Setting NIKOLA_DEBUG should give you all the debug info possible.
Suggested change
|
||||||
init_template_trace_logging("templates_log.txt") | ||||||
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. Consider using the
Suggested change
|
||||||
|
||||||
|
||||||
# Push warnings to logging | ||||||
|
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.
Nope. Every theme must inherit from at least
base
/base-jinja
, we explicitly refuse to support any other scenario (even if the code does not prevent this, we would prefer not to admit that it is a possibility, and we reserve the right to break it at any time.)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 have a humble nice little blog in mind. For that, I absolutely want my HTML generated without any
<div>
in it. I want to prove that semantic HTML can be done. I also think that my little web site should work nicely without any Javascript (ROCA-style). This is not theory, this has really been my intention when I came to Nikola in the first place. If something in the templating changes, I'm willing to accept that my site will break on Nikola update and I'll have to fix.I am willing to accept that I'll have to do a lot of theme customization to get that. As a platform as it stands now, Nikola would technically let me do this.
You are saying that Nikola strategically does not support my use case and I should go look elsewhere?
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.
See https://www.famsik.de/opinions for background. In my opinion, Nikola could serve nicely for people who want to do experiments with stuff like that. But accepting that as a valid Nikola use case is a project-political decision.
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.
Thinking about it a bit further: From my point of view, it would be useful if Nikola would simply officially state that
As for support, that would mean for Nokia a new template requirement needs to be announced in the change file.
Would that be something you'd be willing to do if asked nicely?
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.
Here’s some example wording that might work:
It’s unlikely we’ll ever introduce a new template, but I guess it might be mentioned in the changelog if that happens.
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.
As far as the changelog is concerned: Anything in the templates can be user-changed. So I think Nikola has to mention any change in the template arena in the changelog anyway. I see that as independent of the question "with base or not".
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.
Some stance like the one you suggest would answer my concerns. Thanks!
For some detail fine-tuning: I would prefer to warn people of consequences, yes, but otherwise treat them as adults who are able to make grown-up decisions. So I would think it nicer if we left out the "strongly discouraged" part. Maybe warn people that growing their own theme is harder than they might think at first sight.
As for the "not officially supported": Before people file a bug, we should require them to add the pertinent parent. If that makes the bug go away, it must not be filed.
Anything else the "not officially supported" entails?
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.
“Strongly discouraged” and “not officially supported” are meant to suggest “don’t do this unless you really know what you’re doing”. For user-facing software, phrases like this are a good idea IMO to clearly show the limitations.
“Not officially supported” means basically what you said, i.e. we won’t help with issues caused by a parentless theme, and we don’t guarantee it will always work.
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.
Via the polyfill discussion, a solid reason surfaced why Nikola might rethink its policy of not officially supporting templates without parent.
Where GDPR rules, one needs a certain written agreement with any company before sending web traffic their way. This is a consequence of GDPR art 28, in particular section 2.. (I've personally been one of many developers who ported all references to Google fonts from external to locally hosted, in the web presence of a big Germany company (some 300.000+ employed).)
I believe small, private web sites are inside the target group of Nikola. People responsible for such web sites might not have the time and legal power to establish any such agreements legally needed. So they may choose to use no external resources whatsoever, but self-host everything their web site needs.
Nikola makes not promises regarding self-hosting presently. Indeed, build-in Nikola templates freely use external resources. Any Nikola version update might conceivably introduce or change external references in the HTML produced. Wanting to play it safe is a very solid reason to use a template without parent.
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.
Generally there's the option
use_cdn
, but as #3763 shows this isn't always respected, like forpolyfill.io
.I'm personally also using a template without a parent for my sites. (More precisely I have my own base template, and some templates deriving from my base.)