search

hyde / hyde

A Python Static Website Generator (Presently Unmaintained).
http://hyde.github.io
MIT License
1.63k stars 245 forks source link

Document Jinja2 extensions #45

Open alanhogan opened 13 years ago

alanhogan commented 13 years ago

Apparently things like {% refer to X as y %} and {% do X if Y %} are Hyde-specific Jinja2 extensions. While cool and useful, this somewhat hinders naïve template re-use in another system (e.g. Tornado or Django). What exactly the new refer keyword does is confusing as well, as it sounds like the set keyword but appears Hyde-specific and somewhat more magical.

navilan commented 13 years ago

Hi,

Interesting. Can you give me an example of a template reuse outside of hyde?

I am wondering if the refer tag should translate to import and mark as a noop. An example would certainly clarify this.

Thanks Lakshmi

alanhogan commented 13 years ago

Sure, what I’m doing right now is working with a Tornado instance which is using the Jinja2 framework and, initially, the FileSystemLoader set to use the same directory as all my Hyde templates.

The intention is to re-use the base and slightly more specific (e.g. two-column) layouts already used by Hyde, for more dynamic pages of the site.

So this runs into trouble for a couple reasons:

  1. Undefined media_url (easy enough to fix)…
  2. Jinja2 parse errors due to use of refer and apparently do as well, in the macros.j2 file that renders the nav in the default Hyde distribution (which I am using and appreciate).

It does initially make sense to map refer → import and mark → noop (without trying it)…

I can get rid of the refers from macros easily enough by splitting off the render_excerpt macro into a different file, leaving just common macros like render_nav.

But render_nav itself — which I would like to use in the Tornado environment as well — uses:

  {% do classes.append('active') if active -%}

and apparently Jinja2 doesn’t really get that by default. Thoughts?

navilan commented 13 years ago

I see. Yes, splitting off the macros file seems like a good idea - better than redefining the refer and mark tags for jinja2.

do is a jinja2 extension that needs to be configured.

Here is how default extensions are configured in hyde: https://github.com/hyde/hyde/blob/master/hyde/ext/templates/jinja.py#L516-526

You can do the same wherever you initialize jinja2.