@anydigital/eleventy-bricks 0.24.0 → 0.26.0

package/README.md

@@ -1,4 +1,4 @@
-# eleventy-bricks
+# `@anydigital/eleventy-bricks`
 
 A collection of helpful utilities and filters for Eleventy (11ty).
 
@@ -25,9 +25,9 @@ export default function (eleventyConfig) {
   eleventyConfig.addPlugin(eleventyBricks, {
     mdAutoRawTags: true,
     mdAutoNl2br: true,
-    mdAutoLinkFavicons: true,
+    autoLinkFavicons: true,
     siteData: true,
-    filters: ["attr", "where_in", "merge", "remove_tag", "if", "attr_concat", "fetch"],
+    filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "fetch"],
   });
 
   // Your other configuration...
@@ -43,9 +43,9 @@ module.exports = function (eleventyConfig) {
   eleventyConfig.addPlugin(eleventyBricks, {
     mdAutoRawTags: true,
     mdAutoNl2br: true,
-    mdAutoLinkFavicons: true,
+    autoLinkFavicons: true,
     siteData: true,
-    filters: ["attr", "where_in", "merge", "remove_tag", "if", "attr_concat", "fetch"],
+    filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "fetch"],
   });
 
   // Your other configuration...
@@ -64,9 +64,9 @@ Import only the specific helpers you need without using the plugin:
 import {
   mdAutoRawTags,
   mdAutoNl2br,
-  mdAutoLinkFavicons,
-  setAttrFilter,
-  whereInFilter,
+  autoLinkFavicons,
+  attrSetFilter,
+  attrIncludesFilter,
   mergeFilter,
   removeTagFilter,
   ifFilter,
@@ -78,14 +78,17 @@ import {
 export default function (eleventyConfig) {
   mdAutoRawTags(eleventyConfig);
   mdAutoNl2br(eleventyConfig);
-  mdAutoLinkFavicons(eleventyConfig);
-  setAttrFilter(eleventyConfig);
-  whereInFilter(eleventyConfig);
+  autoLinkFavicons(eleventyConfig);
+  attrSetFilter(eleventyConfig);
+  attrIncludesFilter(eleventyConfig);
   mergeFilter(eleventyConfig);
   removeTagFilter(eleventyConfig);
   ifFilter(eleventyConfig);
   attrConcatFilter(eleventyConfig);
-  fetchFilter(eleventyConfig); // Only if @11ty/eleventy-fetch is installed
+  // fetchFilter is only available if @11ty/eleventy-fetch is installed
+  if (fetchFilter) {
+    fetchFilter(eleventyConfig);
+  }
   siteData(eleventyConfig);
 
   // Your other configuration...
@@ -98,9 +101,9 @@ export default function (eleventyConfig) {
 const {
   mdAutoRawTags,
   mdAutoNl2br,
-  mdAutoLinkFavicons,
-  setAttrFilter,
-  whereInFilter,
+  autoLinkFavicons,
+  attrSetFilter,
+  attrIncludesFilter,
   mergeFilter,
   removeTagFilter,
   ifFilter,
@@ -112,14 +115,17 @@ const {
 module.exports = async function (eleventyConfig) {
   await mdAutoRawTags(eleventyConfig);
   await mdAutoNl2br(eleventyConfig);
-  await mdAutoLinkFavicons(eleventyConfig);
-  await setAttrFilter(eleventyConfig);
-  await whereInFilter(eleventyConfig);
+  await autoLinkFavicons(eleventyConfig);
+  await attrSetFilter(eleventyConfig);
+  await attrIncludesFilter(eleventyConfig);
   await mergeFilter(eleventyConfig);
   await removeTagFilter(eleventyConfig);
   await ifFilter(eleventyConfig);
   await attrConcatFilter(eleventyConfig);
-  await fetchFilter(eleventyConfig); // Only if @11ty/eleventy-fetch is installed
+  // fetchFilter is only available if @11ty/eleventy-fetch is installed
+  if (fetchFilter) {
+    await fetchFilter(eleventyConfig);
+  }
   await siteData(eleventyConfig);
 
   // Your other configuration...
@@ -132,18 +138,18 @@ module.exports = async function (eleventyConfig) {
 
 When using the plugin (Option 1), you can configure which helpers to enable:
 
-| Option               | Type            | Default | Description                                                      |
-| -------------------- | --------------- | ------- | ---------------------------------------------------------------- |
-| `mdAutoRawTags`      | boolean         | `false` | Enable the mdAutoRawTags preprocessor for Markdown files         |
-| `mdAutoNl2br`        | boolean         | `false` | Enable the mdAutoNl2br preprocessor to convert \n to `<br>` tags |
-| `mdAutoLinkFavicons` | boolean         | `false` | Enable the mdAutoLinkFavicons transform to add favicons to links |
-| `siteData`           | boolean         | `false` | Enable site.year and site.prod global data                       |
-| `filters`            | array of string | `[]`    | Array of filter names to enable (see Available Filters section)  |
+| Option             | Type            | Default | Description                                                      |
+| ------------------ | --------------- | ------- | ---------------------------------------------------------------- |
+| `mdAutoRawTags`    | boolean         | `false` | Enable the mdAutoRawTags preprocessor for Markdown files         |
+| `mdAutoNl2br`      | boolean         | `false` | Enable the mdAutoNl2br preprocessor to convert \n to `<br>` tags |
+| `autoLinkFavicons` | boolean         | `false` | Enable the autoLinkFavicons transform to add favicons to links   |
+| `siteData`         | boolean         | `false` | Enable site.year and site.prod global data                       |
+| `filters`          | array of string | `[]`    | Array of filter names to enable (see Available Filters section)  |
 
 **Available filter names for the `filters` array:**
 
-- `'attr'` - Override object attributes
-- `'where_in'` - Filter collections by attribute values
+- `'attr_set'` - Override object attributes
+- `'attr_includes'` - Filter collections by attribute values
 - `'merge'` - Merge arrays or objects
 - `'remove_tag'` - Remove HTML elements from content
 - `'if'` - Inline conditional/ternary operator
@@ -156,188 +162,80 @@ When using the plugin (Option 1), you can configure which helpers to enable:
 eleventyConfig.addPlugin(eleventyBricks, {
   mdAutoRawTags: true,
   mdAutoNl2br: true,
-  mdAutoLinkFavicons: true,
+  autoLinkFavicons: true,
   siteData: true,
-  filters: ["attr", "where_in", "merge", "remove_tag", "if", "attr_concat", "fetch"],
+  filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "fetch"],
 });
 ```
 
-## Available 11ty Helpers
-
-### mdAutoRawTags
-
-Prevents Nunjucks syntax from being processed in Markdown files by automatically wrapping `{{`, `}}`, `{%`, and `%}` with `{% raw %}` tags.
-
-**Why use this?**
-
-When writing documentation or tutorials about templating in Markdown files, you often want to show Nunjucks/Liquid syntax as literal text. This preprocessor automatically escapes these special characters so they display as-is instead of being processed by the template engine.
-
-**Usage:**
-
-1. Enable `mdAutoRawTags` in your Eleventy config:
-
-```javascript
-import { mdAutoRawTags } from "@anydigital/eleventy-bricks";
-
-export default function (eleventyConfig) {
-  mdAutoRawTags(eleventyConfig);
-  // Or use as plugin:
-  // eleventyConfig.addPlugin(eleventyBricks, { mdAutoRawTags: true });
-}
-```
-
-**Example:**
-
-Before `mdAutoRawTags`, writing this in Markdown:
-
-```markdown
-Use {{ variable }} to output variables.
-```
-
-Would try to process `{{ variable }}` as a template variable. With `mdAutoRawTags`, it displays exactly as written.
-
-### mdAutoNl2br
-
-Automatically converts `\n` sequences to `<br>` tags in Markdown content. This is particularly useful for adding line breaks inside Markdown tables where standard newlines don't work.
-
-**Why use this?**
-
-Markdown tables don't support multi-line content in cells. By using `\n` in your content, this preprocessor will convert it to `<br>` tags, allowing you to display line breaks within table cells and other content.
-
-**Usage:**
-
-1. Enable `mdAutoNl2br` in your Eleventy config:
-
-```javascript
-import { mdAutoNl2br } from "@anydigital/eleventy-bricks";
-
-export default function (eleventyConfig) {
-  mdAutoNl2br(eleventyConfig);
-  // Or use as plugin:
-  // eleventyConfig.addPlugin(eleventyBricks, { mdAutoNl2br: true });
-}
-```
-
-**Example:**
-
-In your Markdown file:
-
-```markdown
-| Column 1               | Column 2                          |
-| ---------------------- | --------------------------------- |
-| Line 1\nLine 2\nLine 3 | Another cell\nWith multiple lines |
-```
-
-Will render as:
-
-```html
-<td>Line 1<br />Line 2<br />Line 3</td>
-<td>Another cell<br />With multiple lines</td>
-```
-
-**Note:** This processes literal `\n` sequences (backslash followed by 'n'), not actual newline characters. Type `\n` in your source files where you want line breaks.
-
-### mdAutoLinkFavicons
-
-Automatically adds favicon images from Google's favicon service to links that display plain URLs or domain names. This transform processes all HTML output files and adds inline favicon images next to link text that appears to be a plain URL.
-
-**Why use this?**
-
-When you have links in your content that display raw URLs or domain names (like `https://example.com/page`), adding favicons provides a visual indicator of the external site. This transform automatically detects these plain-text URL links and enhances them with favicon images, making them more visually appealing and easier to recognize.
-
-**Usage:**
-
-1. Enable `mdAutoLinkFavicons` in your Eleventy config:
-
-```javascript
-import { mdAutoLinkFavicons } from "@anydigital/eleventy-bricks";
-
-export default function (eleventyConfig) {
-  mdAutoLinkFavicons(eleventyConfig);
-  // Or use as plugin:
-  // eleventyConfig.addPlugin(eleventyBricks, { mdAutoLinkFavicons: true });
-}
-```
-
-**How it works:**
-
-The transform:
-
-1. Scans all HTML output files for `<a>` tags
-2. Checks if the link text appears to be a plain URL or domain
-3. Extracts the domain from the URL
-4. Removes the domain from the link text (keeping only the path)
-5. Adds a favicon image from Google's favicon service inline with the remaining text
-
-**Example:**
+### Additional Exports
 
-Before transformation:
+The plugin also exports the following utility functions for advanced usage:
 
-```html
-<a href="https://github.com/anydigital/eleventy-bricks">https://github.com/anydigital/eleventy-bricks</a>
-```
+- `transformAutoRaw(content)`: The transform function used by `mdAutoRawTags` preprocessor. Can be used programmatically to wrap Nunjucks syntax with raw tags.
+- `transformNl2br(content)`: The transform function used by `mdAutoNl2br` preprocessor. Can be used programmatically to convert `\n` sequences to `<br>` tags.
+- `isPlainUrlText(linkText, domain)`: Helper function that checks if link text looks like a plain URL or domain.
+- `cleanLinkText(linkText, domain)`: Helper function that cleans link text by removing protocol, domain, and leading slash.
+- `buildFaviconLink(attrs, domain, text)`: Helper function that builds HTML for a link with favicon.
+- `transformLink(match, attrs, url, linkText)`: The transform function used by `autoLinkFavicons` that transforms a single link to include a favicon.
+- `replaceLinksInHtml(content, transformer)`: Helper function that replaces all anchor links in HTML content with transformed versions.
+- `attrIncludes(collection, attrName, targetValue)`: The core logic for filtering collection items by checking if an attribute array includes a target value. Can be used programmatically to filter collections.
+- `merge(first, ...rest)`: The core merge function used by the `merge` filter. Can be used programmatically to merge arrays or objects.
+- `removeTag(html, tagName)`: The core function used by the `remove_tag` filter. Can be used programmatically to remove HTML tags from content.
+- `iff(trueValue, condition, falseValue)`: The core conditional function used by the `if` filter. Can be used programmatically as a ternary operator.
+- `attrConcat(obj, attr, values)`: The core function used by the `attr_concat` filter. Can be used programmatically to concatenate values to an attribute array.
+- `attrSet(obj, key, value)`: The core function used by the `attr_set` filter. Can be used programmatically to override object attributes.
 
-After transformation:
+<!--TRICKS-->
 
-```html
-<a href="https://github.com/anydigital/eleventy-bricks" class="whitespace-nowrap" target="_blank">
-  <i><img src="https://www.google.com/s2/favicons?domain=github.com&sz=32" /></i>
-  <span>/anydigital/eleventy-bricks</span>
-</a>
-```
+## Tricks from [Eleventy Bricks](https://github.com/anydigital/eleventy-bricks) {#eleventy-bricks}
 
-**Rules:**
+### Filters
 
-- Only applies to links where the text looks like a plain URL (contains the domain or starts with `http://`/`https://`)
-- Removes the protocol and domain from the display text
-- Removes the trailing slash from the display text
-- Only applies if at least 3 characters remain after removing the domain (to avoid showing favicons for bare domain links)
-- Uses Google's favicon service at `https://www.google.com/s2/favicons?domain=DOMAIN&sz=32`
-- Adds `target="_blank"` to the transformed links (only if not already present)
-- Adds `whitespace-nowrap` class to the link
-- Wraps the link text in a `<span>` element
-- The favicon is wrapped in an `<i>` tag for easy styling
+|      Input | Nunjucks                                                                       | Liquid <hr>                                          |
+| ---------: | ------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| {.divider} | Logical                                                                        |
+|  `ANY \| ` | `default(VALUE)` <br>= `d(...)`                                                | `default: VALUE`                                     |
+|   `ANY \|` | [`if(TEST, OP, VALUE)`](#if) <sub>currently only `if(TEST)`</sub>              | [`if: TEST, OP, VALUE`](#if)                         |
+| {.divider} | On objects                                                                     |
+|   `OBJ \|` | [`merge(OBJ2)`](#merge)                                                        | [`merge: OBJ2`](#merge)                              |
+| {.divider} | On object attributes                                                           |
+|   `OBJ \|` | `selectattr(BOOL_ATTR)`                                                        | `where: ATTR, VALUE`                                 |
+|   `OBJ \|` | `rejectattr(BOOL_ATTR)`                                                        | N/A                                                  |
+|   `OBJ \|` | [`attr_includes(ARRAY_ATTR, VALUE)`](#attr_includes) <sub>was `where_in`</sub> | [`attr_includes: ARRAY_ATTR, VALUE`](#attr_includes) |
+|   `OBJ \|` | [`attr_set(ATTR, VALUE)`](#attr_set) <sub>was `attr`</sub>                     | [`attr_set: ATTR, VALUE`](#attr_set)                 |
+|   `OBJ \|` | [`attr_concat(ARRAY_ATTR, ARRAY2)`](#attr_concat)                              | [`attr_concat: ARRAY_ATTR, ARRAY2`](#attr_concat)    |
+| {.divider} | Textual                                                                        |
+|  `HTML \|` | `striptags`                                                                    | `strip_html`                                         |
+|  `HTML \|` | [`remove_tag(TAG)`](#remove_tag)                                               | [`remove_tag: TAG`](#remove_tag)                     |
+|   `STR \|` | `remove: STR2`                                                                 | `remove: STR2`                                       |
+| {.divider} | Other                                                                          |
+|   `URL \|` | [`fetch`](#fetch)                                                              | [`fetch`](#fetch)                                    |
 
-**Styling:**
+Ref:
 
-You can style the favicon icons with CSS:
+- https://mozilla.github.io/nunjucks/templating.html#builtin-filters
+- https://shopify.github.io/liquid/
 
-```css
-/* Style the favicon wrapper */
-a i {
-  display: inline-block;
-  margin-right: 0.25em;
-}
-
-/* Style the favicon image */
-a i img {
-  width: 16px;
-  height: 16px;
-  vertical-align: middle;
-}
-```
-
-**Note:** This transform only processes HTML output files (those ending in `.html`). It does not modify the original content files.
-
-### attr
+#### `attr_set`
 
 A filter that creates a new object with an overridden attribute value. This is useful for modifying data objects in templates without mutating the original.
 
 **Why use this?**
 
-When working with Eleventy data, you sometimes need to modify an object's properties for a specific use case. The `attr` filter provides a clean way to create a modified copy of an object without affecting the original.
+When working with Eleventy data, you sometimes need to modify an object's properties for a specific use case. The `attr_set` filter provides a clean way to create a modified copy of an object without affecting the original.
 
 **Usage:**
 
-1. Enable the `attr` filter in your Eleventy config:
+1. Enable the `attr_set` filter in your Eleventy config:
 
 ```javascript
-import { setAttrFilter } from "@anydigital/eleventy-bricks";
+import { attrSetFilter } from "@anydigital/eleventy-bricks";
 
 export default function (eleventyConfig) {
-  setAttrFilter(eleventyConfig);
+  attrSetFilter(eleventyConfig);
   // Or use as plugin:
-  // eleventyConfig.addPlugin(eleventyBricks, { filters: ['attr'] });
+  // eleventyConfig.addPlugin(eleventyBricks, { filters: ['attr_set'] });
 }
 ```
 
@@ -345,7 +243,7 @@ export default function (eleventyConfig) {
 
 ```njk
 {# Create a modified version of a page object #}
-{% set modifiedPage = page | attr('title', 'New Title') %}
+{% set modifiedPage = page | attr_set('title', 'New Title') %}
 
 <h1>{{ modifiedPage.title }}</h1>
 <p>Original title: {{ page.title }}</p>
@@ -372,61 +270,50 @@ A new object with the specified attribute set to the given value. The original o
 
 ```njk
 {# Override a single attribute #}
-{% set updatedPost = post | attr('featured', true) %}
+{% set updatedPost = post | attr_set('featured', true) %}
 
-{# Chain multiple attr filters #}
+{# Chain multiple attr_set filters #}
 {% set modifiedPost = post
-  | attr('category', 'blog')
-  | attr('priority', 1)
+  | attr_set('category', 'blog')
+  | attr_set('priority', 1)
 %}
 
 {# Use in loops #}
 {% for item in collection %}
-  {% set enhancedItem = item | attr('processed', true) %}
+  {% set enhancedItem = item | attr_set('processed', true) %}
   {# ... use enhancedItem ... #}
 {% endfor %}
 ```
 
-### where_in
+#### `attr_includes`
 
-A filter that filters collection items by attribute value. It checks if an item's attribute matches a target value. If the attribute is an array, it checks if the array includes the target value. Supports nested attribute names using dot notation.
+A filter that filters collection items by checking if an attribute array includes a target value. Supports nested attribute names using dot notation.
 
 **Why use this?**
 
-When working with Eleventy collections, you often need to filter items based on front matter data. The `where_in` filter provides a flexible way to filter by any attribute, with special handling for array attributes (like tags) and support for nested properties using dot notation.
+When working with Eleventy collections, you often need to filter items based on tags or other array attributes in front matter. The `attr_includes` filter provides a flexible way to filter by any array attribute, with support for nested properties using dot notation.
 
 **Usage:**
 
-1. Enable the `where_in` filter in your Eleventy config:
+1. Enable the `attr_includes` filter in your Eleventy config:
 
 ```javascript
-import { whereInFilter } from "@anydigital/eleventy-bricks";
+import { attrIncludesFilter } from "@anydigital/eleventy-bricks";
 
 export default function (eleventyConfig) {
-  whereInFilter(eleventyConfig);
+  attrIncludesFilter(eleventyConfig);
   // Or use as plugin:
-  // eleventyConfig.addPlugin(eleventyBricks, { filters: ['where_in'] });
+  // eleventyConfig.addPlugin(eleventyBricks, { filters: ['attr_includes'] });
 }
 ```
 
 2. Use the filter in your templates:
 
-**Filter by exact attribute match:**
-
-```njk
-{# Get all posts with category 'blog' #}
-{% set blogPosts = collections.all | where_in('data.category', 'blog') %}
-
-{% for post in blogPosts %}
-  <h2>{{ post.data.title }}</h2>
-{% endfor %}
-```
-
 **Filter by array attribute (tags):**
 
 ```njk
 {# Get all posts that include 'javascript' tag #}
-{% set jsPosts = collections.all | where_in('data.tags', 'javascript') %}
+{% set jsPosts = collections.all | attr_includes('data.tags', 'javascript') %}
 
 {% for post in jsPosts %}
   <h2>{{ post.data.title }}</h2>
@@ -437,15 +324,14 @@ export default function (eleventyConfig) {
 
 - `collection`: The collection to filter (array of items)
 - `attrName`: The attribute name to check (string, supports dot notation for nested properties)
-- `targetValue`: The value to match against (any type)
+- `targetValue`: The value to check for in the array (any type)
 
 **Features:**
 
-- Works with any attribute in front matter
-- Supports dot notation for nested properties (e.g., `'data.tags'`, `'data.author.name'`)
-- Special handling for array attributes (uses `includes()` check)
+- Works with any array attribute in front matter
+- Supports dot notation for nested properties (e.g., `'data.tags'`, `'data.author.roles'`)
 - Returns empty array if collection is invalid
-- Filters out items without the specified attribute
+- Filters out items where the specified attribute is not an array or doesn't exist
 
 **Examples:**
 
@@ -463,20 +349,17 @@ priority: 1
 Template usage:
 
 ```njk
-{# Filter by category (using dot notation for nested properties) #}
-{% set blogPosts = collections.all | where_in('data.category', 'blog') %}
-
-{# Filter by tag (array) #}
-{% set jsTutorials = collections.all | where_in('data.tags', 'javascript') %}
+{# Filter by tag (array) using dot notation for nested properties #}
+{% set jsTutorials = collections.all | attr_includes('data.tags', 'javascript') %}
 
-{# Filter by numeric value #}
-{% set highPriority = collections.all | where_in('data.priority', 1) %}
+{# Filter by numeric value in array #}
+{% set highPriority = collections.all | attr_includes('data.priorities', 1) %}
 
 {# Chain filters #}
-{% set recentBlogPosts = collections.all | where_in('data.category', 'blog') | reverse | limit(5) %}
+{% set recentTutorials = collections.all | attr_includes('data.tags', 'tutorial') | reverse | limit(5) %}
 ```
 
-### merge
+#### `merge`
 
 A filter that merges arrays or objects together, similar to Twig's merge filter. For arrays, it concatenates them. For objects, it performs a shallow merge where later values override earlier ones.
 
@@ -543,8 +426,8 @@ export default function (eleventyConfig) {
 
 ```njk
 {# Combine featured and regular posts #}
-{% set featuredPosts = collections.all | where_in('data.featured', true) %}
-{% set regularPosts = collections.all | where_in('data.featured', false) %}
+{% set featuredPosts = collections.all | attr_includes('data.featured', true) %}
+{% set regularPosts = collections.all | attr_includes('data.featured', false) %}
 {% set allPosts = featuredPosts | merge(regularPosts) %}
 
 {# Merge page metadata with defaults #}
@@ -564,7 +447,7 @@ export default function (eleventyConfig) {
 {% set config = defaults | merge(siteConfig, pageConfig, userPrefs) %}
 ```
 
-### remove_tag
+#### `remove_tag`
 
 A filter that removes a specified HTML element from provided HTML content. It removes the tag along with its content, including self-closing tags.
 
@@ -637,7 +520,7 @@ export default function (eleventyConfig) {
 
 While this filter can help sanitize HTML content, it should not be relied upon as the sole security measure. For critical security requirements, use a dedicated HTML sanitization library on the server side before content reaches your templates.
 
-### if
+#### `if`
 
 An inline conditional/ternary operator filter that returns one value if a condition is truthy, and another if it's falsy. Similar to Nunjucks' inline if syntax.
 
@@ -712,7 +595,7 @@ export default function (eleventyConfig) {
 {% set cssClass = 'featured' | if: post.featured | upper %}
 ```
 
-### attr_concat
+#### `attr_concat`
 
 A filter that concatenates values to an attribute array, returning a new object with the combined array. Useful for adding items to arrays like tags, classes, or other list-based attributes.
 
@@ -794,7 +677,7 @@ A new object with the specified attribute containing the combined unique array.
 {% endfor %}
 ```
 
-### fetch
+#### `fetch`
 
 A filter that fetches content from remote URLs or local files. For remote URLs, it uses `@11ty/eleventy-fetch` to download and cache files. For local paths, it reads files relative to the input directory.
 
@@ -927,7 +810,164 @@ your-project/
 
 **Note:** The filter returns raw text content. Use Eleventy's built-in filters like `| safe`, `| markdown`, or `| fromJson` to process the content as needed.
 
-### siteData
+### Transforms
+
+#### mdAutoRawTags
+
+Prevents Nunjucks syntax from being processed in Markdown files by automatically wrapping `{{`, `}}`, `{%`, and `%}` with `{% raw %}` tags.
+
+**Why use this?**
+
+When writing documentation or tutorials about templating in Markdown files, you often want to show Nunjucks/Liquid syntax as literal text. This preprocessor automatically escapes these special characters so they display as-is instead of being processed by the template engine.
+
+**Usage:**
+
+1. Enable `mdAutoRawTags` in your Eleventy config:
+
+```javascript
+import { mdAutoRawTags } from "@anydigital/eleventy-bricks";
+
+export default function (eleventyConfig) {
+  mdAutoRawTags(eleventyConfig);
+  // Or use as plugin:
+  // eleventyConfig.addPlugin(eleventyBricks, { mdAutoRawTags: true });
+}
+```
+
+**Example:**
+
+Before `mdAutoRawTags`, writing this in Markdown:
+
+```markdown
+Use {{ variable }} to output variables.
+```
+
+Would try to process `{{ variable }}` as a template variable. With `mdAutoRawTags`, it displays exactly as written.
+
+#### mdAutoNl2br
+
+Automatically converts `\n` sequences to `<br>` tags in Markdown content. This is particularly useful for adding line breaks inside Markdown tables where standard newlines don't work.
+
+**Why use this?**
+
+Markdown tables don't support multi-line content in cells. By using `\n` in your content, this preprocessor will convert it to `<br>` tags, allowing you to display line breaks within table cells and other content.
+
+**Usage:**
+
+1. Enable `mdAutoNl2br` in your Eleventy config:
+
+```javascript
+import { mdAutoNl2br } from "@anydigital/eleventy-bricks";
+
+export default function (eleventyConfig) {
+  mdAutoNl2br(eleventyConfig);
+  // Or use as plugin:
+  // eleventyConfig.addPlugin(eleventyBricks, { mdAutoNl2br: true });
+}
+```
+
+**Example:**
+
+In your Markdown file:
+
+```markdown
+| Column 1               | Column 2                          |
+| ---------------------- | --------------------------------- |
+| Line 1\nLine 2\nLine 3 | Another cell\nWith multiple lines |
+```
+
+Will render as:
+
+```html
+<td>Line 1<br />Line 2<br />Line 3</td>
+<td>Another cell<br />With multiple lines</td>
+```
+
+**Note:** This processes literal `\n` sequences (backslash followed by 'n'), not actual newline characters. Type `\n` in your source files where you want line breaks.
+
+#### autoLinkFavicons
+
+Automatically adds favicon images from Google's favicon service to links that display plain URLs or domain names. This transform processes all HTML output files and adds inline favicon images next to link text that appears to be a plain URL.
+
+**Why use this?**
+
+When you have links in your content that display raw URLs or domain names (like `https://example.com/page`), adding favicons provides a visual indicator of the external site. This transform automatically detects these plain-text URL links and enhances them with favicon images, making them more visually appealing and easier to recognize.
+
+**Usage:**
+
+1. Enable `autoLinkFavicons` in your Eleventy config:
+
+```javascript
+import { autoLinkFavicons } from "@anydigital/eleventy-bricks";
+
+export default function (eleventyConfig) {
+  autoLinkFavicons(eleventyConfig);
+  // Or use as plugin:
+  // eleventyConfig.addPlugin(eleventyBricks, { autoLinkFavicons: true });
+}
+```
+
+**How it works:**
+
+The transform:
+
+1. Scans all HTML output files for `<a>` tags
+2. Checks if the link text appears to be a plain URL or domain
+3. Extracts the domain from the URL
+4. Removes the domain from the link text (keeping only the path)
+5. Adds a favicon image from Google's favicon service inline with the remaining text
+
+**Example:**
+
+Before transformation:
+
+```html
+<a href="https://github.com/anydigital/eleventy-bricks">https://github.com/anydigital/eleventy-bricks</a>
+```
+
+After transformation:
+
+```html
+<a href="https://github.com/anydigital/eleventy-bricks" class="whitespace-nowrap" target="_blank">
+  <i><img src="https://www.google.com/s2/favicons?domain=github.com&sz=32" /></i>
+  <span>/anydigital/eleventy-bricks</span>
+</a>
+```
+
+**Rules:**
+
+- Only applies to links where the text looks like a plain URL (contains the domain or starts with `http://`/`https://`)
+- Removes the protocol and domain from the display text
+- Removes the trailing slash from the display text
+- Only applies if at least 3 characters remain after removing the domain (to avoid showing favicons for bare domain links)
+- Uses Google's favicon service at `https://www.google.com/s2/favicons?domain=DOMAIN&sz=32`
+- Adds `target="_blank"` to the transformed links (only if not already present)
+- Adds `whitespace-nowrap` class to the link
+- Wraps the link text in a `<span>` element
+- The favicon is wrapped in an `<i>` tag for easy styling
+
+**Styling:**
+
+You can style the favicon icons with CSS:
+
+```css
+/* Style the favicon wrapper */
+a i {
+  display: inline-block;
+  margin-right: 0.25em;
+}
+
+/* Style the favicon image */
+a i img {
+  width: 16px;
+  height: 16px;
+  vertical-align: middle;
+}
+```
+
+**Note:** This transform only processes HTML output files (those ending in `.html`). It does not modify the original content files.
+
+### Global Data
 
 Adds global site data to your Eleventy project, providing commonly needed values that can be accessed in all templates.
 
@@ -1003,26 +1043,18 @@ export default function (eleventyConfig) {
 {% endif %}
 ```
 
-### Additional Exports
-
-The plugin also exports the following utility functions for advanced usage:
+### Symlinked Configuration Files
 
-- `transformAutoRaw(content)`: The transform function used by `mdAutoRawTags` preprocessor. Can be used programmatically to wrap Nunjucks syntax with raw tags.
-- `transformNl2br(content)`: The transform function used by `mdAutoNl2br` preprocessor. Can be used programmatically to convert `\n` sequences to `<br>` tags.
-- `isPlainUrlText(linkText, domain)`: Helper function that checks if link text looks like a plain URL or domain.
-- `cleanLinkText(linkText, domain)`: Helper function that cleans link text by removing protocol, domain, and leading slash.
-- `buildFaviconLink(attrs, domain, text)`: Helper function that builds HTML for a link with favicon.
-- `transformLink(match, attrs, url, linkText)`: The transform function used by `mdAutoLinkFavicons` that transforms a single link to include a favicon.
-- `merge(first, ...rest)`: The core merge function used by the `merge` filter. Can be used programmatically to merge arrays or objects.
-- `removeTag(html, tagName)`: The core function used by the `remove_tag` filter. Can be used programmatically to remove HTML tags from content.
-- `iff(trueValue, condition, falseValue)`: The core conditional function used by the `if` filter. Can be used programmatically as a ternary operator.
-- `attrConcat(obj, attr, values)`: The core function used by the `attr_concat` filter. Can be used programmatically to concatenate values to an attribute array.
+The package includes pre-configured starter files in `node_modules/@anydigital/eleventy-bricks/src/` that you can symlink to your project for quick setup:
 
-## Starter Configuration Files
+Benefits of Symlinking:
 
-The package includes pre-configured starter files in `node_modules/@anydigital/eleventy-bricks/src/` that you can symlink to your project for quick setup:
+- **Always up-to-date**: Configuration automatically updates when you upgrade the package
+- **Less maintenance**: No need to manually sync configuration changes
+- **Quick setup**: Get started immediately with best-practice configurations
+- **Easy customization**: Override specific settings by creating your own config that imports from the symlinked version
 
-### Available Starter Files
+If you prefer to customize the configurations extensively, you can copy the files instead.
 
 #### eleventy.config.js
 
@@ -1030,6 +1062,7 @@ A fully-configured Eleventy config file with:
 
 - All eleventy-bricks plugins enabled
 - Eleventy Navigation plugin
+- Table of Contents plugin (conditionally loaded if installed)
 - Markdown-it with anchors and attributes
 - YAML data support
 - CLI input directory support
@@ -1041,6 +1074,16 @@ A fully-configured Eleventy config file with:
 npm install @11ty/eleventy-navigation markdown-it markdown-it-anchor markdown-it-attrs js-yaml minimist
 ```
 
+**Optional dependencies:**
+
+```bash
+# For the fetch filter
+npm install @11ty/eleventy-fetch
+
+# For table of contents generation
+npm install @uncenter/eleventy-plugin-toc
+```
+
 **Symlink to your project:**
 
 ```bash
@@ -1058,25 +1101,6 @@ mkdir -p admin
 ln -s ../node_modules/@anydigital/eleventy-bricks/src/admin/index.html admin/index.html
 ```
 
-### Benefits of Symlinking
-
-- **Always up-to-date**: Configuration automatically updates when you upgrade the package
-- **Less maintenance**: No need to manually sync configuration changes
-- **Quick setup**: Get started immediately with best-practice configurations
-- **Easy customization**: Override specific settings by creating your own config that imports from the symlinked version
-
-### Alternative: Copy Files
-
-If you prefer to customize the configurations extensively, you can copy the files instead:
-
-```bash
-cp node_modules/@anydigital/eleventy-bricks/src/eleventy.config.js .
-mkdir -p admin
-cp node_modules/@anydigital/eleventy-bricks/src/admin/index.html admin/
-```
-
-## Development Workflow Setup
-
 ### Using the `do` Folder Pattern
 
 This package provides a pre-configured `do` folder setup that helps organize your development workflow using npm workspaces. The `do` folder contains scripts for building and running your Eleventy project.
@@ -1137,68 +1161,3 @@ npm run build
 - **Reusable workflows**: Update scripts by upgrading the package
 - **Workspace isolation**: Scripts run in their own workspace context
 - **Easy maintenance**: No need to manually maintain build scripts
-
-## CLI Helper Commands
-
-After installing this package, the `download-files` command becomes available:
-
-### download-files
-
-A CLI command that downloads external files to your project based on URLs specified in your `package.json`.
-
-**Usage:**
-
-1. Add a `_downloadFiles` field to your project's `package.json` with URL-to-path mappings:
-
-```json
-{
-  "_downloadFiles": {
-    "https://example.com/library.js": "src/vendor/library.js",
-    "https://cdn.example.com/styles.css": "public/css/external.css"
-  }
-}
-```
-
-2. Run the download command:
-
-```bash
-npx download-files
-```
-
-**Options:**
-
-- `-o, --output <dir>`: Specify an output directory where all files will be downloaded (relative paths in `_downloadFiles` will be resolved relative to this directory)
-
-```bash
-# Download all files to a specific directory
-npx download-files --output public
-```
-
-**Features:**
-
-- Downloads multiple files from external URLs
-- Automatically creates directories if they don't exist
-- Overwrites existing files
-- Continues downloading remaining files even if some fail
-- Provides clear progress and error messages
-- Returns appropriate exit codes for CI/CD integration
-
-**Use Cases:**
-
-- Download third-party libraries and assets
-- Fetch external resources during build processes
-- Keep vendored files up to date
-- Automate dependency downloads that aren't available via npm
-
-## Requirements
-
-- Node.js >= 18.0.0
-- Eleventy >= 3.0.0
-
-## License
-
-MIT
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.