docs: blurry_image tag

docs/content/plugins/write-a-jinja-extension-plugin.md

@@ -0,0 +1,30 @@
++++
+"@type" = "WebPage"
+name = "Plugins: write a Jinja extension plugin"
+abstract = "Documentation for Blurry's Jinja extension plugins"
+datePublished = 2024-04-28
++++
+
+# Plugins: write an Jinja extension plugin
+
+Blurry makes it easy to add [custom Jinja extensions](https://jinja.palletsprojects.com/en/3.1.x/extensions/) to your site.
+What is a Jinja extension?
+From the Jinja docs:
+
+> Jinja supports extensions that can add extra filters, tests, globals or even extend the parser. The main motivation of extensions is to move often used code into a reusable class like adding support for internationalization.
+
+With [custom extensions](https://jinja.palletsprojects.com/en/3.1.x/extensions/#module-jinja2.ext) you can add custom tags to Jinja, like Blurry's `{% blurry_image %}` tag.
+
+## Example: `{% blurry_image %}`
+
+This tag finds the optimized version of an image at the specified URL, and optionally of the specified size.
+You can find it in Blurry's source code in `blurry/plugins/jinja_plugins/blurry_image_extension.py`.
+
+Under the hood the extension uses [`jinja2-simple-tags`](https://github.com/dldevinc/jinja2-simple-tags) to simplify the process of writing a custom extension.
+
+To use a custom Jinja extension you've developed, add the appropriate plugin syntax to your project's `pyproject.toml` file:
+
+```toml
+[tool.poetry.plugins."blurry.jinja_extensions"]
+stars = "{{ yourproject.your_extension_file }}:YourExtension"
+```

docs/content/templates/syntax.md

@@ -3,6 +3,7 @@
 name = "Templates: syntax"
 abstract = "Documentation for Blurry's template files and Jinja syntax"
 datePublished = 2023-04-09
+dateModified = 2023-04-28
 image = {contentUrl = "../images/schema.org-logo.png"}
 +++
 
@@ -42,3 +43,30 @@ If your templates require more granularity than the Schema.org types, you can wr
 [blurry.template_schema_types]
 ContextWebPage = 'WebPage'
 ```
+
+## Blurry-included plugins
+
+Blurry ships with some plugins to simplify writing templates.
+
+### `{% blurry_image %}`
+
+This extension adds the `{% blurry_image %}` tag to simplify including images reference in [Markdown front matter](../content/markdown.md) in your templates.
+It does a few things:
+
+- Finds the image in your build directory
+- Extracts the images width & height
+- Builds an `<img>` tag with width, height, and the othwer attributes specified in the tag
+
+#### Examples
+
+Basic example:
+
+```jinja
+{% blurry_image page.thumbnailUrl, alt="Image description" %}
+```
+
+Example with explicit width (image with this width must be present in the build folder):
+
+```jinja
+{% blurry_image page.thumbnailUrl, 250, id="image-id", class="responsive-image", loading="lazy" %}
+```

docs/templates/base.html

@@ -63,6 +63,7 @@
                         <li><a href="/plugins/intro/" rel="noreferrer">Intro</a></li>
                         <li><a href="/plugins/write-a-markdown-plugin/" rel="noreferrer">Write a Markdown plugin</a></li>
                         <li><a href="/plugins/write-an-html-plugin/" rel="noreferrer">Write an HTML plugin</a></li>
+                        <li><a href="/plugins/write-a-jinja-extension-plugin/" rel="noreferrer">Write a Jinja extension plugin</a></li>
                         <li><a href="/plugins/write-a-jinja-filter-plugin/" rel="noreferrer">Write a Jinja filter plugin</a></li>
                     </ul>
                 </li>