From 71c0087bf22eabb2ca4cc86c06b47a69534adfa7 Mon Sep 17 00:00:00 2001
From: Mark Dumay <61946753+markdumay@users.noreply.github.com>
Date: Sat, 11 Apr 2026 16:07:17 +0200
Subject: [PATCH] feat(blocks): add category filter example to list
 documentation

Adds a "Category Filter" section to the list block docs demonstrating the
new filter and filter_col arguments. Includes a new table-filter-hook.html
partial that renders a three-column table with a category column sourced
from each page's front matter, used as the live example.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 content/blocks/list.md                        | 38 +++++++++++++++++++
 .../_partials/assets/table-filter-hook.html   | 15 ++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 layouts/_partials/assets/table-filter-hook.html

diff --git a/content/blocks/list.md b/content/blocks/list.md
index 77a56d2..b9c5c5f 100644
--- a/content/blocks/list.md
+++ b/content/blocks/list.md
@@ -73,6 +73,44 @@ You can then use `sortable`, `paginate`, and `searchable` to enable inline sorti
 {{< /example-bookshop >}}
 <!-- markdownlint-enable MD037 -->
 
+### Category Filter
+
+Use `filter` to add a button group above the table that shows only rows matching a specific category. Set `filter_col` to the zero-indexed column in your hook's table that contains the category value. An **All** button is always prepended and selected by default.
+
+The filter works alongside `sortable`, `paginate`, and `searchable` — sorting and pagination continue to operate on the filtered result set.
+
+<!-- markdownlint-disable MD037 -->
+{{< example-bookshop lang="bookshop" >}}
+
+```yml
+- _bookshop_name: list
+  heading:
+    title: Recent articles
+    align: start
+  input:
+    section: blog
+    reverse: false
+    sort: date
+  hide_empty: false
+  hook: assets/table-filter-hook
+  filter:
+    - featured
+    - tutorial
+  filter_col: 1
+  sortable: true
+  background:
+    color: body-tertiary
+    subtle: false
+  justify: start
+```
+
+{{< /example-bookshop >}}
+<!-- markdownlint-enable MD037 -->
+
+Define the hook partial in your site's `layouts/_partials` folder. The following example renders a custom Markdown table that includes a `category` column sourced from each page's front matter.
+
+{{< file file="./layouts/_partials/assets/table-filter-hook.html" full=false lang="go-template" >}}
+
 ### Custom List
 
 Customize the list by providing a `hook` partial.
diff --git a/layouts/_partials/assets/table-filter-hook.html b/layouts/_partials/assets/table-filter-hook.html
new file mode 100644
index 0000000..73c8787
--- /dev/null
+++ b/layouts/_partials/assets/table-filter-hook.html
@@ -0,0 +1,15 @@
+{{ $pages := .pages | default dict }}
+
+{{ $content := printf "| %s | %s | %s |\n|-|-|-|\n" (T "article") (T "category") (T "published") }}
+{{ range $pages }}
+    {{ $cat := .Params.category | default "general" }}
+    {{ if site.Params.env_bookshop_live }}
+        {{ $content = printf "%s[%s](#!) | %s | %s |\n" $content .title $cat (now | time.Format "2006-01-02") }}
+    {{ else }}
+        {{ $content = printf "%s[%s](%s) | %s | %s |\n" $content .LinkTitle .RelPermalink $cat
+            (.PublishDate | time.Format "2006-01-02")
+        }}
+    {{ end }}
+{{ end }}
+
+{{ return $content }}