accept local templates

jinja2content/README.md

@@ -1,23 +1,24 @@
 # Jinja2 Content
 
 This plugin allows the use of Jinja2 directives inside your pelican
-articles and pages. This template rendering is done before the final html
-is generated, i.e. before your theme's `article.html` is applied. This
+articles and pages.  This template rendering is done before the final html
+is generated, i.e. before your theme's `article.html` is applied.  This
 means the context and jinja variables usually visible to your article
 template **ARE NOT** available at this time.
 
 All code that needs those variables (`article`, `category`, etc) should be
-put inside the theme's template logic. As such, the main use of this plugin
-is to automatically generate parts of your articles.
+put inside the theme's template logic.  As such, the main use of this
+plugin is to automatically generate parts of your articles.
 
 
 ## Example
 
-One usage is to embed repetitive html code into Markdown articles. Since
+One usage is to embed repetitive html code into Markdown articles.  Since
 Markdown doesn't care for layout, if anything more sophisticated than just
 displaying an image is necessary, one is forced to embed html in Markdown
-articles (at the very least, hardcode `<div>` tags and then fix it with the
-theme's CSS). However, with `jinja2content`, one can do the following.
+articles (at the very least, hardcode `<div>` tags and then select them
+from the theme's CSS).  However, with `jinja2content`, one can do the
+following.
 
 File `my-cool-article.md`
 ```
@@ -43,9 +44,24 @@ Where file `img_desc.html` contains:
 {%- endmacro %}
 ```
 
+The result will be:
+```
+# My cool title
+
+My cool content.
+
+<div class="img-desc">
+  <p><img src="/images/my-cool-image.png" title="This is a cool tooltip"></p>
+  <p><em>This is a very cool image.</em></p>
+</div>
+```
+
+After this, the Markdown will be rendered into html and only then the
+theme's templates will be applied.
+
 In this way, Markdown articles have more control over the content that is
-passed to the theme's `article.html`, without the need to pollute the
-Markdown with html. Another added benefit is that now `img_desc` is
+passed to the theme's `article.html` template, without the need to pollute
+the Markdown with html.  Another added benefit is that now `img_desc` is
 reusable across articles.
 
 Note that templates rendered with `jinja2content` can contain Markdown as
@@ -53,12 +69,18 @@ well as html, since they are added before the Markdown content is converted
 to html.
 
 
+## Configuration
+
+This plugin accepts the setting "JINJA2CONTENT_TEMPLATES" which should be
+set to a path relative to 'PATH' (the main content directory).
+`jinja2content` will look for templates inside this directory. If they are
+not found here, the theme's templates folder is used.
+
+
 ## Notes
 
-+ Only Markdown supported at this moment. Adding .rst support shouldn't be
-  too hard, and you can ask for it here.
-+ All templates `include`d in this way must be placed in your theme's
-  `templates` directory.
++ Only Markdown supported at this moment.  Adding .rst support shouldn't be
+  too hard, and you can ask for it by opening an issue.
 + This plugin is intended to replace
   [pelican-jinj2content](https://github.com/joachimneu/pelican-jinja2content/tree/f73ef9b1ef1ee1f56c80757b4190b53f8cd607d1)
   which hasn't been developed in a while and generated empty `<p>` tags in

jinja2content/jinja2content.py

@@ -3,7 +3,7 @@ import os
 from pelican import signals
 from pelican.readers import Markdown, MarkdownReader
 from pelican.utils import pelican_open
-from jinja2 import Environment, FileSystemLoader
+from jinja2 import Environment, FileSystemLoader, ChoiceLoader
 
 
 class JinjaMarkdownReader(MarkdownReader):
@@ -11,11 +11,19 @@ class JinjaMarkdownReader(MarkdownReader):
     def __init__(self, *args, **kwargs):
         super(JinjaMarkdownReader, self).__init__(*args, **kwargs)
 
-        templates_dir = os.path.join(self.settings['THEME'], 'templates')
-        self._env = Environment(
-            trim_blocks=True, lstrip_blocks=True,
-            loader=FileSystemLoader(templates_dir),
-            extensions=self.settings['JINJA_EXTENSIONS'])
+        # will look first in 'JINJA2CONTENT_TEMPLATES', by default the
+        # content root path, then in the theme's templates
+        local_templates_dir = self.settings.get('JINJA2CONTENT_TEMPLATES', '.')
+        local_templates_dir = os.path.join(self.settings['PATH'], local_templates_dir)
+        theme_templates_dir = os.path.join(self.settings['THEME'], 'templates')
+        loader = ChoiceLoader([
+            FileSystemLoader(local_templates_dir),
+            FileSystemLoader(theme_templates_dir)])
+
+        self.env = Environment(trim_blocks=True, lstrip_blocks=True,
+                               extensions=self.settings['JINJA_EXTENSIONS'],
+                               loader=loader)
+
 
     def read(self, source_path):
         """Parse content and metadata of markdown files.
@@ -23,11 +31,11 @@ class JinjaMarkdownReader(MarkdownReader):
         Rendering them as jinja templates first.
 
         """
-
         self._source_path = source_path
         self._md = Markdown(extensions=self.extensions)
+
         with pelican_open(source_path) as text:
-            text = self._env.from_string(text).render()
+            text = self.env.from_string(text).render()
             content = self._md.convert(text)
 
         metadata = self._parse_metadata(self._md.Meta)