From e531346214e0fffabad911dfd2108d37f388b30c Mon Sep 17 00:00:00 2001
From: John Franey <1728528+johnfraney@users.noreply.github.com>
Date: Thu, 29 Feb 2024 00:18:20 -0400
Subject: [PATCH] docs: document Jinja filter plugins (#57)

---
 docs/content/plugins/intro.md                 |  8 +++-
 .../plugins/write-a-jinja-filter-plugin.md    | 43 +++++++++++++++++++
 docs/templates/base.html                      |  1 +
 3 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 docs/content/plugins/write-a-jinja-filter-plugin.md

diff --git a/docs/content/plugins/intro.md b/docs/content/plugins/intro.md
index 05a6d0c..27bf8f3 100644
--- a/docs/content/plugins/intro.md
+++ b/docs/content/plugins/intro.md
@@ -16,7 +16,11 @@ Blurry ships with a simple plugin infrastructure that makes it easy to write and
 
 ## How to write a plugin
 
-See [Plugins: write a Markdown plugin](./write-a-markdown-plugin.md) and [Plugins: write an HTML plugin](./write-an-html-plugin.md) for more information.
+See the docs for the type of plugin you'd like to write:
+
+- [Plugins: write a Markdown plugin](./write-a-markdown-plugin.md)
+- [Plugins: write an HTML plugin](./write-an-html-plugin.md)
+- [Plugins: write a Jinja filter plugin](./write-a-jinja-filter-plugin.md)
 
 ## How to register a plugin
 
@@ -37,5 +41,5 @@ It registers a Blurry Markdown plugin in its `pyproject.toml` file using [Poetry
 blur_blurry_name = "blurry_plugin_blur_blurry_name:blur_blurry_name"
 ```
 
-Blurry [dogfoods](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) its own plugin architecture for HTML and Markdown plugins, too.
+Blurry [dogfoods](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) its own plugin architecture, too.
 See which plugins are registered in [Blurry's `pyproject.toml` file](https://github.com/blurry-dev/blurry/blob/main/pyproject.toml).
diff --git a/docs/content/plugins/write-a-jinja-filter-plugin.md b/docs/content/plugins/write-a-jinja-filter-plugin.md
new file mode 100644
index 0000000..be447f0
--- /dev/null
+++ b/docs/content/plugins/write-a-jinja-filter-plugin.md
@@ -0,0 +1,43 @@
++++
+"@type" = "WebPage"
+name = "Plugins: write a Jinja filter plugin"
+abstract = "Documentation for Blurry's Jinja filter plugins"
+datePublished = 2024-02-29
++++
+
+# Plugins: write an Jinja filter plugin
+
+Blurry makes it easy to add [custom Jinja filters](https://jinja.palletsprojects.com/en/3.1.x/api/#custom-filters) to your site.
+What is a Jinja filter?
+From the Jinja docs:
+
+> Filters are Python functions that take the value to the left of the filter as the first argument and produce a new value. Arguments passed to the filter are passed after the value.
+>
+> For example, the filter `{{ 42|myfilter(23) }}` is called behind the scenes as myfilter(42, 23).
+
+## Example: "stars"
+
+This function outputs a number of Unicode stars corresponding to the input, rounding to the nearest half-star.
+
+```python
+import math
+
+STAR_EMPTY = "☆"
+STAR_FILLED = "★"
+STAR_HALF_FILLED = "⯪"
+
+
+def float_to_stars(num: float, max: int = 5) -> str:
+    whole_stars = math.floor(num) * STAR_FILLED
+    part_star = STAR_HALF_FILLED if num - len(whole_stars) > 0 else ""
+    non_empty_stars = f"{whole_stars}{part_star}"
+
+    return f"{non_empty_stars:{STAR_EMPTY}{'<'}{max}}"
+```
+
+To use it, add the appropriate plugin syntax to your `pyproject.toml` file:
+
+```toml
+[tool.poetry.plugins."blurry.jinja_filter_plugins"]
+stars = "{{ yourproject }}:float_to_stars"
+```
diff --git a/docs/templates/base.html b/docs/templates/base.html
index 311bc47..d21aae0 100644
--- a/docs/templates/base.html
+++ b/docs/templates/base.html
@@ -58,6 +58,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-filter-plugin/" rel="noreferrer">Write a Jinja filter plugin</a></li>
                     </ul>
                 </li>
             </ul>