Update README

jinja2content/README.md

@@ -1,23 +1,31 @@
 # 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
-means the context and jinja variables usually visible to your article
-template **ARE NOT** available at this time.
+This plugin allows the use of Jinja2 directives inside your pelican articles and pages.
 
-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.
+In this approach, your content is *first* rendered by the Jinja template engine. The result
+is then passed to the normal pelican reader as usual. There are two consequences for usage.
+First, this means the Pelican context and jinja variables [usually
+visible](http://docs.getpelican.com/en/stable/themes.html#templates-and-variables) to your
+article or page template are _not_ available at rendering time. Second, it means that if any
+of your input content could be parsed as Jinja directives, they will be rendered as such.
+This is unlikely to happen accidentally, but it's good to be aware of.
+
+All input that needs Pelican variables such as `article`, `category`, etc., should be put
+inside your *theme's* templating.  As such, the main use of this plugin is to automatically
+generate parts of your articles or pages.
+
+Markdown, reStructured Text, and HTML input are all supported. Note that by enabling this
+plugin, all input files of these file types will be preprocessed with the Jinja renderer.
+It is not currently supported to selectively enable or disable `jinja2content` for only some of
+these input sources.
 
 
 ## Example
 
-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 select them
-from the theme's CSS).  However, with `jinja2content`, one can do the
+One usage is to embed repetitive HTML in Markdown articles. Since Markdown doesn't allow
+customization of layout, if anything more sophisticated than just displaying an image is
+necessary, one is forced to embed HTML in Markdown articles (i.e. 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`
@@ -56,32 +64,51 @@ My cool content.
 </div>
 ```
 
-After this, the Markdown will be rendered into html and only then the
+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` template, without the need to pollute
-the Markdown with html.  Another added benefit is that now `img_desc` is
+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
-well as html, since they are added before the Markdown content is converted
+well as HTML, since they are added before the Markdown content is converted
 to html.
 
 
+## Usage
+
+Enable the `jinja2content` plugin in your project in [the usual
+manner](http://docs.getpelican.com/en/stable/plugins.html#how-to-use-plugins).
+
+```
+PLUGINS = [
+    # ...
+    "jinja2content",
+]
+```
+
+
 ## Configuration
 
-This plugin accepts the setting "JINJA2CONTENT_TEMPLATES" which should be
-set to a list of paths relative to 'PATH' (the main content directory).
-`jinja2content` will look for templates inside these directories, in order.
-If they are not found in any, the theme's templates folder is used.
+This plugin accepts the setting `JINJA2CONTENT_TEMPLATES` which should be set to a list of
+paths relative to `PATH` (the main content directory, usually `"content"`).  `jinja2content`
+will look for templates inside these directories, in order.  If they are not found in any,
+the theme's templates folder is used.
+
+
+## Extension
+
+This plugin is structured such that it should be quite easy to extend readers for other file
+types to also render Jinja template logic. It should be sufficient to create a new reader
+class that inherents from the `JinjaContentMixin` and then your desired reader class. See
+class definitions in the source for examples.
 
 
-## Notes
+## Acknowledgements
 
-+ 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
-  the final html output.
+- Created by @Leonardo.
+- Updated to support rst and HTML input by @micahjsmith.
+- Replaces [pelican-jinj2content](https://github.com/joachimneu/pelican-jinja2content/tree/f73ef9b1ef1ee1f56c80757b4190b53f8cd607d1),
+which had become unmaintained.