@anydigital/eleventy-bricks 0.26.0 → 0.27.1

package/README.md

@@ -27,7 +27,7 @@ export default function (eleventyConfig) {
     mdAutoNl2br: true,
     autoLinkFavicons: true,
     siteData: true,
-    filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "fetch"],
+    filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "section", "fetch"],
   });
 
   // Your other configuration...
@@ -45,7 +45,7 @@ module.exports = function (eleventyConfig) {
     mdAutoNl2br: true,
     autoLinkFavicons: true,
     siteData: true,
-    filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "fetch"],
+    filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "section", "fetch"],
   });
 
   // Your other configuration...
@@ -71,6 +71,7 @@ import {
   removeTagFilter,
   ifFilter,
   attrConcatFilter,
+  sectionFilter,
   fetchFilter,
   siteData,
 } from "@anydigital/eleventy-bricks";
@@ -85,6 +86,7 @@ export default function (eleventyConfig) {
   removeTagFilter(eleventyConfig);
   ifFilter(eleventyConfig);
   attrConcatFilter(eleventyConfig);
+  sectionFilter(eleventyConfig);
   // fetchFilter is only available if @11ty/eleventy-fetch is installed
   if (fetchFilter) {
     fetchFilter(eleventyConfig);
@@ -108,6 +110,7 @@ const {
   removeTagFilter,
   ifFilter,
   attrConcatFilter,
+  sectionFilter,
   fetchFilter,
   siteData,
 } = require("@anydigital/eleventy-bricks");
@@ -122,6 +125,7 @@ module.exports = async function (eleventyConfig) {
   await removeTagFilter(eleventyConfig);
   await ifFilter(eleventyConfig);
   await attrConcatFilter(eleventyConfig);
+  await sectionFilter(eleventyConfig);
   // fetchFilter is only available if @11ty/eleventy-fetch is installed
   if (fetchFilter) {
     await fetchFilter(eleventyConfig);
@@ -154,6 +158,7 @@ When using the plugin (Option 1), you can configure which helpers to enable:
 - `'remove_tag'` - Remove HTML elements from content
 - `'if'` - Inline conditional/ternary operator
 - `'attr_concat'` - Concatenate values to an attribute array
+- `'section'` - Extract named sections from content marked with HTML comments
 - `'fetch'` - Fetch remote URLs or local files (requires `@11ty/eleventy-fetch`)
 
 **Example:**
@@ -164,7 +169,7 @@ eleventyConfig.addPlugin(eleventyBricks, {
   mdAutoNl2br: true,
   autoLinkFavicons: true,
   siteData: true,
-  filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "fetch"],
+  filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "section", "fetch"],
 });
 ```
 
@@ -172,50 +177,40 @@ eleventyConfig.addPlugin(eleventyBricks, {
 
 The plugin also exports the following utility functions for advanced usage:
 
-- `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.
+- `transformAutoRaw(content)`: The processor function used by `mdAutoRawTags` preprocessor. Can be used programmatically to wrap Nunjucks syntax with raw tags.
+- `transformNl2br(content)`: The processor function used by `mdAutoNl2br` preprocessor. Can be used programmatically to convert `\\n` sequences to `\u003cbr\u003e` 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.
+- `transformLink(match, attrs, url, linkText)`: The processor function used by `autoLinkFavicons` that processes a single link to include a favicon.
+- `replaceLinksInHtml(content, processor)`: Helper function that replaces all anchor links in HTML content with processed 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.
+- `section(content, sectionName)`: The core function used by the `section` filter. Can be used programmatically to extract named sections from content.
 
-<!--TRICKS-->
-
-## Tricks from [Eleventy Bricks](https://github.com/anydigital/eleventy-bricks) {#eleventy-bricks}
-
-### Filters
-
-|      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)                                    |
-
-Ref:
-
-- https://mozilla.github.io/nunjucks/templating.html#builtin-filters
-- https://shopify.github.io/liquid/
+## Features
+
+<!--section:filters-h3-->
+
+### Universal 11ty filters <small>for `.njk` & `.liquid`</small> <sub>by https://github.com/anydigital/eleventy-bricks</sub>
+
+|      Input | Filter                            | Arguments                                          |
+| ---------: | --------------------------------- | -------------------------------------------------- |
+| {.divider} | Logical filters:                  |
+|   `ANY \|` | [`if`](#if)                       | `TEST, OP, VALUE` <sub>currently only `TEST`</sub> |
+| {.divider} | Filters for objects:              |
+|   `OBJ \|` | [`merge`](#merge)                 | `OBJ2`                                             |
+|   `OBJ \|` | [`attr_set`](#attr_set)           | `ATTR, VALUE`                                      |
+|   `OBJ \|` | [`attr_concat`](#attr_concat)     | `ATTR, ARRAY2`                                     |
+|   `OBJ \|` | [`attr_includes`](#attr_includes) | `ATTR, VALUE`                                      |
+| {.divider} | Other filters:                    |
+|   `URL \|` | [`fetch`](#fetch)                 |                                                    |
+|  `HTML \|` | [`section`](#section)             | `NAME`                                             |
+|  `HTML \|` | [`remove_tag`](#remove_tag)       | `TAG`                                              |
 
 #### `attr_set`
 
@@ -520,6 +515,103 @@ 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.
 
+#### `section`
+
+A filter that extracts a named section from content marked with HTML comments. This is useful for splitting a single content file (like a Markdown post) into multiple parts that can be displayed and styled independently in your templates.
+
+**Why use this?**
+
+When working with Markdown content in Eleventy, you're usually limited to a single `content` variable. The `section` filter allows you to define multiple named sections within your content using simple HTML comments, giving you granular control over where different parts of your content appear in your layout.
+
+**Usage:**
+
+1. Enable the `section` filter in your Eleventy config:
+
+```javascript
+import { sectionFilter } from "@anydigital/eleventy-bricks";
+
+export default function (eleventyConfig) {
+  sectionFilter(eleventyConfig);
+  // Or use as plugin:
+  // eleventyConfig.addPlugin(eleventyBricks, { filters: ['section'] });
+}
+```
+
+2. Mark sections in your content file (e.g., `post.md`):
+
+```markdown
+# My Post
+
+<¡--section:intro-->
+
+This is the introduction that appears at the top of the page.
+
+<¡--section:main-->
+
+This is the main body of the post with all the details.
+
+<¡--section:summary,sidebar-->
+
+This content appears in both the summary and the sidebar!
+```
+
+3. Use the filter in your templates:
+
+```njk
+{# Get the intro section #}
+<div class="page-intro">
+  {{ content | section('intro') | safe }}
+</div>
+
+{# Get the main section #}
+<article>
+  {{ content | section('main') | safe }}
+</article>
+
+{# Get the sidebar section #}
+<aside>
+  {{ content | section('sidebar') | safe }}
+</aside>
+```
+
+**Parameters:**
+
+- `content`: The string content to process (usually `content` variable)
+- `sectionName`: The name(s) of the section to extract (string)
+
+**Features:**
+
+- **Multiple names**: A single section can have multiple names separated by commas: `<¡--section:name1,name2-->`
+- **Case-insensitive**: Section names are matched without regard to case
+- **Multiple occurrences**: If a section name appears multiple times, the filter concatenates all matching sections
+- **Non-destructive**: Returns extracted content without modifying the original input
+- **EOF support**: Sections continue until the next `<¡--section*-->` marker or the end of the file
+
+**Examples:**
+
+```njk
+{# Extract multiple sections with same name #}
+{# Example content has two &lt;!--section:note--> blocks #}
+<div class="notes-box">
+  {{ content | section('note') | safe }}
+</div>
+
+{# Use case-insensitive names #}
+{{ content | section('INTRO') | safe }}
+
+{# Handle missing sections gracefully (returns empty string) #}
+{% set footer = content | section('non-existent-section') %}
+{% if footer %}
+  <footer>{{ footer | safe }}</footer>
+{% endif %}
+```
+
+**Syntax Rules:**
+
+- Sections start with: `<¡--section:NAME-->` or `<¡--section:NAME1,NAME2-->`
+- Sections end at the next `<¡--section*-->` marker or end of file
+- Whitespace around names and inside comments is automatically trimmed
+
 #### `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.
@@ -810,61 +902,108 @@ 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.
 
-### Transforms
+<!--section:data&processors-h3-->
 
-#### mdAutoRawTags
+### Global `site` data helpers
 
-Prevents Nunjucks syntax from being processed in Markdown files by automatically wrapping `{{`, `}}`, `{%`, and `%}` with `{% raw %}` tags.
+Adds global `site` data to your Eleventy project, providing commonly needed values that can be accessed in all templates:
 
-**Why use this?**
+| Variable          | Value                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `{{ site.year }}` | The current year as a number (e.g., `2026`)                                                                  |
+| `{{ site.prod }}` | Boolean indicating if running in production mode (`true` for `eleventy build`, `false` for `eleventy serve`) |
 
-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.
+<details>
+<summary>Quick setup</summary>
 
-**Usage:**
+```sh
+npm install @anydigital/eleventy-bricks
+```
 
-1. Enable `mdAutoRawTags` in your Eleventy config:
+Then choose one of the following options:
 
-```javascript
-import { mdAutoRawTags } from "@anydigital/eleventy-bricks";
+1. ```js {data-caption="As a plugin in eleventy.config.js (balanced)"}
+   import eleventyBricksPlugin from "@anydigital/eleventy-bricks";
 
-export default function (eleventyConfig) {
-  mdAutoRawTags(eleventyConfig);
-  // Or use as plugin:
-  // eleventyConfig.addPlugin(eleventyBricks, { mdAutoRawTags: true });
-}
-```
+   export default function (eleventyConfig) {
+     eleventyConfig.addPlugin(eleventyBricksPlugin, { siteData: true });
+   }
+   ```
+
+2. ```js {data-caption="Individual import in eleventy.config.js (minimal)"}
+   import { siteData } from "@anydigital/eleventy-bricks";
+
+   export default function (eleventyConfig) {
+     siteData(eleventyConfig);
+   }
+   ```
+
+3. ```sh {data-caption="Symlink entire eleventy.config.js (easiest)"}
+   ln -s node_modules/@anydigital/eleventy-bricks/src/eleventy.config.js
+   ```
+
+{.list-[upper-roman]}
+
+</details>
+
+### `mdAutoRawTags` preprocessor
+
+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.
 
 **Example:**
 
 Before `mdAutoRawTags`, writing this in Markdown:
 
 ```markdown
-Use {{ variable }} to output variables.
+### Using {{ variable }} to output variables
 ```
 
 Would try to process `{{ variable }}` as a template variable. With `mdAutoRawTags`, it displays exactly as written.
 
-#### mdAutoNl2br
+<details>
+<summary>Quick setup</summary>
 
-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.
+```sh
+npm install @anydigital/eleventy-bricks
+```
 
-**Why use this?**
+Then choose one of the following options:
 
-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.
+1. ```js {data-caption="As a plugin in eleventy.config.js (balanced)"}
+   import eleventyBricksPlugin from "@anydigital/eleventy-bricks";
 
-**Usage:**
+   export default function (eleventyConfig) {
+     eleventyConfig.addPlugin(eleventyBricksPlugin, { mdAutoRawTags: true });
+   }
+   ```
 
-1. Enable `mdAutoNl2br` in your Eleventy config:
+2. ```js {data-caption="Individual import in eleventy.config.js (minimal)"}
+   import { mdAutoRawTags } from "@anydigital/eleventy-bricks";
 
-```javascript
-import { mdAutoNl2br } from "@anydigital/eleventy-bricks";
+   export default function (eleventyConfig) {
+     mdAutoRawTags(eleventyConfig);
+   }
+   ```
 
-export default function (eleventyConfig) {
-  mdAutoNl2br(eleventyConfig);
-  // Or use as plugin:
-  // eleventyConfig.addPlugin(eleventyBricks, { mdAutoNl2br: true });
-}
-```
+3. ```sh {data-caption="Symlink entire eleventy.config.js (easiest)"}
+   ln -s node_modules/@anydigital/eleventy-bricks/src/eleventy.config.js
+   ```
+
+{.list-[upper-roman]}
+
+</details>
+
+### `mdAutoNl2br` converter
+
+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.
 
 **Example:**
 
@@ -885,31 +1024,48 @@ Will render as:
 
 **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
+<details>
+<summary>Quick setup</summary>
 
-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.
+```sh
+npm install @anydigital/eleventy-bricks
+```
 
-**Why use this?**
+Then choose one of the following options:
 
-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.
+1. ```js {data-caption="As a plugin in eleventy.config.js (balanced)"}
+   import eleventyBricksPlugin from "@anydigital/eleventy-bricks";
 
-**Usage:**
+   export default function (eleventyConfig) {
+     eleventyConfig.addPlugin(eleventyBricksPlugin, { mdAutoNl2br: true });
+   }
+   ```
 
-1. Enable `autoLinkFavicons` in your Eleventy config:
+2. ```js {data-caption="Individual import in eleventy.config.js (minimal)"}
+   import { mdAutoNl2br } from "@anydigital/eleventy-bricks";
 
-```javascript
-import { autoLinkFavicons } from "@anydigital/eleventy-bricks";
+   export default function (eleventyConfig) {
+     mdAutoNl2br(eleventyConfig);
+   }
+   ```
 
-export default function (eleventyConfig) {
-  autoLinkFavicons(eleventyConfig);
-  // Or use as plugin:
-  // eleventyConfig.addPlugin(eleventyBricks, { autoLinkFavicons: true });
-}
-```
+3. ```sh {data-caption="Symlink entire eleventy.config.js (easiest)"}
+   ln -s node_modules/@anydigital/eleventy-bricks/src/eleventy.config.js
+   ```
 
-**How it works:**
+{.list-[upper-roman]}
+
+</details>
+
+### `autoLinkFavicons` processor
+
+Automatically adds favicon images from Google's favicon service to links that display plain URLs or domain names. This processor 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 processor automatically detects these plain-text URL links and enhances them with favicon images, making them more visually appealing and easier to recognize.
 
-The transform:
+**How it works:**
 
 1. Scans all HTML output files for `<a>` tags
 2. Checks if the link text appears to be a plain URL or domain
@@ -919,13 +1075,13 @@ The transform:
 
 **Example:**
 
-Before transformation:
+Before processing:
 
 ```html
 <a href="https://github.com/anydigital/eleventy-bricks">https://github.com/anydigital/eleventy-bricks</a>
 ```
 
-After transformation:
+After processing:
 
 ```html
 <a href="https://github.com/anydigital/eleventy-bricks" class="whitespace-nowrap" target="_blank">
@@ -941,124 +1097,49 @@ After transformation:
 - 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 `target="_blank"` to the processed 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.
-
-**Why use this?**
-
-Many websites need access to the current year (for copyright notices) and environment information (to conditionally enable features based on production vs development). This helper provides these as global `site` data without manually setting them up.
-
-**Usage:**
-
-1. Enable `siteData` in your Eleventy config:
+<details>
+<summary>Quick setup</summary>
 
-```javascript
-import { siteData } from "@anydigital/eleventy-bricks";
-
-export default function (eleventyConfig) {
-  siteData(eleventyConfig);
-  // Or use as plugin:
-  // eleventyConfig.addPlugin(eleventyBricks, { siteData: true });
-}
-```
-
-2. Use the global data in your templates:
-
-**Current Year:**
-
-```njk
-<footer>
-  <p>&copy; {{ site.year }} Your Company Name. All rights reserved.</p>
-</footer>
-```
-
-**Environment Check:**
-
-```njk
-{% if site.prod %}
-  <!-- Production-only features -->
-  <script async src="https://www.googletagmanager.com/gtag/js?id=GA_TRACKING_ID"></script>
-{% else %}
-  <!-- Development-only features -->
-  <div class="dev-toolbar">Development Mode</div>
-{% endif %}
+```sh
+npm install @anydigital/eleventy-bricks
 ```
 
-**Available Data:**
-
-- `site.year`: The current year as a number (e.g., `2026`)
-- `site.prod`: Boolean indicating if running in production mode (`true` for `eleventy build`, `false` for `eleventy serve`)
+Then choose one of the following options:
 
-**Features:**
-
-- Automatically updates the year value
-- Detects production vs development mode based on `ELEVENTY_RUN_MODE` environment variable
-- Available globally in all templates without manual setup
-- No configuration required
-
-**Examples:**
-
-```njk
-{# Copyright notice #}
-<p>Copyright &copy; {{ site.year }} My Site</p>
+1. ```js {data-caption="As a plugin in eleventy.config.js (balanced)"}
+   import eleventyBricksPlugin from "@anydigital/eleventy-bricks";
 
-{# Conditional loading of analytics #}
-{% if site.prod %}
-  <script src="/analytics.js"></script>
-{% endif %}
+   export default function (eleventyConfig) {
+     eleventyConfig.addPlugin(eleventyBricksPlugin, { autoLinkFavicons: true });
+   }
+   ```
 
-{# Different behavior in dev vs prod #}
-{% if site.prod %}
-  <link rel="stylesheet" href="/css/styles.min.css">
-{% else %}
-  <link rel="stylesheet" href="/css/styles.css">
-  <script src="/live-reload.js"></script>
-{% endif %}
-```
+2. ```js {data-caption="Individual import in eleventy.config.js (minimal)"}
+   import { autoLinkFavicons } from "@anydigital/eleventy-bricks";
 
-### Symlinked Configuration Files
+   export default function (eleventyConfig) {
+     autoLinkFavicons(eleventyConfig);
+   }
+   ```
 
-The package includes pre-configured starter files in `node_modules/@anydigital/eleventy-bricks/src/` that you can symlink to your project for quick setup:
+3. ```sh {data-caption="Symlink entire eleventy.config.js (easiest)"}
+   ln -s node_modules/@anydigital/eleventy-bricks/src/eleventy.config.js
+   ```
 
-Benefits of Symlinking:
+{.list-[upper-roman]}
 
-- **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
+</details>
 
-If you prefer to customize the configurations extensively, you can copy the files instead.
+<!--section:config-h3-->
 
-#### eleventy.config.js
+### Symlinked `eleventy.config.js` <sub>from https://github.com/anydigital/eleventy-bricks</sub>
 
-A fully-configured Eleventy config file with:
+The package includes a fully-configured Eleventy config file `eleventy.config.js` that you can symlink to your project to get:
 
 - All eleventy-bricks plugins enabled
 - Eleventy Navigation plugin
@@ -1067,30 +1148,27 @@ A fully-configured Eleventy config file with:
 - YAML data support
 - CLI input directory support
 - Symlink support for development
+- _and more_
 
-**Required dependencies:**
-
-```bash
-npm install @11ty/eleventy-navigation markdown-it markdown-it-anchor markdown-it-attrs js-yaml minimist
-```
+**Benefits of symlinking:**
 
-**Optional dependencies:**
+- **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
 
-```bash
-# For the fetch filter
-npm install @11ty/eleventy-fetch
+**Quick setup:**
 
-# For table of contents generation
-npm install @uncenter/eleventy-plugin-toc
+```sh
+npm install @anydigital/eleventy-bricks
+ln -s node_modules/@anydigital/eleventy-bricks/src/eleventy.config.js
 ```
 
-**Symlink to your project:**
+Done! 🎉
 
-```bash
-ln -s node_modules/@anydigital/eleventy-bricks/src/eleventy.config.js eleventy.config.js
-```
+<!--section:cms-h4-->
 
-#### admin/index.html
+### Symlinked CMS
 
 A ready-to-use Sveltia CMS admin interface for content management.
 
@@ -1101,59 +1179,54 @@ mkdir -p admin
 ln -s ../node_modules/@anydigital/eleventy-bricks/src/admin/index.html admin/index.html
 ```
 
-### Using the `do` Folder Pattern
+<!--section:npm-h3-->
+
+### Reusable 11ty npm scripts <small>via npm workspace</small> <sub>from https://github.com/anydigital/eleventy-bricks</sub>
 
 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.
 
-**Setup:**
+**Quick setup:**
 
-1. Create a `do` folder in your project root:
+1. Create a simple folder, which will hold reusable npm scripts:
 
-```bash
-mkdir do
-```
+   ```sh
+   mkdir do
+   ```
 
-2. Symlink the package.json from the eleventy-bricks package:
+2. Install https://github.com/anydigital/eleventy-bricks to reuse default 11ty scripts from there:
 
-```bash
-ln -s node_modules/@anydigital/eleventy-bricks/src/do/package.json do/package.json
-```
+   ```sh
+   npm install @anydigital/eleventy-bricks
+   ```
 
-3. Configure your root `package.json` to use npm workspaces:
+3. Symlink the `do/package.json` containing scripts into your project's `do` folder:
 
-```json
-{
-  "name": "my-project",
-  "workspaces": ["do"],
-  "scripts": {
-    "build": "npm -w do run build",
-    "start": "npm -w do run start"
-  }
-}
-```
+   ```sh
+   cd do
+   ln -s node_modules/@anydigital/eleventy-bricks/src/do/package.json
+   ```
 
-**Usage:**
+4. Finally register `do` folder as npm workspace in your `package.json`, and enjoy default 11ty scripts as simple as:
 
-Run your Eleventy project:
+   ```json {data-caption="YOUR project's package.json"}
+   {
+     "workspaces": ["do"],
+     "scripts": {
+       "start": "npm -w do run start",
+       "stage": "npm -w do run stage",
+       "build": "npm -w do run build"
+     }
+   }
+   ```
 
-```bash
-npm start
-```
-
-Build for production:
-
-```bash
-npm run build
-```
+**Done!** 🎉 Now you can run:
 
-**Available Scripts in `do` folder:**
+- `npm start` to start 11ty dev server with live reload and Tailwind watch mode
+- `npm run stage` to build and serve production-like site locally
+- `npm run build` to finally build the site for production
+- all available scripts: https://github.com/anydigital/eleventy-bricks/blob/main/src/do/package.json
 
-- `build` - Build the site with Eleventy and minify CSS with Tailwind
-- `start` - Start Eleventy dev server with live reload and Tailwind watch mode
-- `stage` - Clean build and serve locally for preview
-- `11ty` - Run Eleventy commands directly
-- `11ty:clean` - Remove the `_site` output directory
-- `tw` - Run Tailwind CSS commands
+**Example setup:** https://github.com/anydigital/sveleven
 
 **Benefits:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anydigital/eleventy-bricks",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "A collection of helpful utilities and filters for Eleventy (11ty)",
   "type": "module",
   "main": "./src/index.js",

package/src/eleventy.config.js

@@ -36,7 +36,7 @@ export default function (eleventyConfig) {
     mdAutoRawTags: true,
     autoLinkFavicons: true,
     siteData: true,
-    filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "fetch"],
+    filters: ["attr_set", "attr_includes", "merge", "remove_tag", "if", "attr_concat", "fetch", "section"],
   });
   if (pluginTOC) {
     eleventyConfig.addPlugin(pluginTOC, {

package/src/filters/section.js

@@ -0,0 +1,62 @@
+/**
+ * Extract a named section from content marked with HTML comments
+ *
+ * @param {string} content - The content to process
+ * @param {string} sectionName - The section name(s) to extract
+ * @returns {string} The extracted section content
+ */
+export function section(content, sectionName) {
+  if (!content || typeof content !== "string") {
+    return content;
+  }
+
+  if (typeof sectionName !== "string" || !sectionName) {
+    return "";
+  }
+
+  // Normalize section name for comparison (trim whitespace)
+  const targetName = sectionName.trim().toLowerCase();
+
+  // Regex to match section markers with content up to the next section or end of string
+  // Captures: (1) section names, (2) content until next section marker or end
+  const sectionRegex = /<!--section:([^>]+)-->([\s\S]*?)(?=<!--section|$)/g;
+
+  let results = [];
+  let match;
+
+  // Find all sections
+  while ((match = sectionRegex.exec(content)) !== null) {
+    const namesStr = match[1];
+    const sectionContent = match[2];
+    const names = namesStr.split(",").map((n) => n.trim().toLowerCase());
+
+    // Check if any of the names match the target
+    if (names.includes(targetName)) {
+      results.push(sectionContent);
+    }
+  }
+
+  // Join all matching sections
+  return results.join("");
+}
+
+/**
+ * section filter - Extract a named section from content
+ *
+ * Usage in templates:
+ *   {{ content | section('intro') }}
+ *   {{ content | section('footer') }}
+ *
+ * Content format:
+ *   <!--section:intro-->
+ *   This is the intro content
+ *   <!--section:main-->
+ *   This is the main content
+ *   <!--section:footer,sidebar-->
+ *   This appears in both footer and sidebar sections
+ *
+ * @param {Object} eleventyConfig - The Eleventy configuration object
+ */
+export function sectionFilter(eleventyConfig) {
+  eleventyConfig.addFilter("section", section);
+}

package/src/filters/section.test.js

@@ -0,0 +1,174 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { section } from "./section.js";
+
+describe("section", () => {
+  it("should extract a single named section", () => {
+    const content = `Before
+<!--section:intro-->
+This is the intro
+<!--section:main-->
+This is the main`;
+
+    const result = section(content, "intro");
+    assert.strictEqual(result, "\nThis is the intro\n");
+  });
+
+  it("should extract section up to the next section marker", () => {
+    const content = `<!--section:first-->
+First content
+<!--section:second-->
+Second content
+<!--section:third-->
+Third content`;
+
+    const result = section(content, "second");
+    assert.strictEqual(result, "\nSecond content\n");
+  });
+
+  it("should extract section up to EOF when no next marker", () => {
+    const content = `<!--section:intro-->
+Intro content
+<!--section:main-->
+Main content that goes to the end`;
+
+    const result = section(content, "main");
+    assert.strictEqual(result, "\nMain content that goes to the end");
+  });
+
+  it("should handle section with multiple names", () => {
+    const content = `<!--section:header,nav-->
+Shared content
+<!--section:main-->
+Main content`;
+
+    const resultHeader = section(content, "header");
+    const resultNav = section(content, "nav");
+
+    assert.strictEqual(resultHeader, "\nShared content\n");
+    assert.strictEqual(resultNav, "\nShared content\n");
+  });
+
+  it("should handle section with multiple names (spaces around commas)", () => {
+    const content = `<!--section:header, nav , top-->
+Shared content
+<!--section:main-->
+Main content`;
+
+    const resultHeader = section(content, "header");
+    const resultNav = section(content, "nav");
+    const resultTop = section(content, "top");
+
+    assert.strictEqual(resultHeader, "\nShared content\n");
+    assert.strictEqual(resultNav, "\nShared content\n");
+    assert.strictEqual(resultTop, "\nShared content\n");
+  });
+
+  it("should return empty string for non-existent section", () => {
+    const content = `<!--section:intro-->
+Content here
+<!--section:main-->
+More content`;
+
+    const result = section(content, "footer");
+    assert.strictEqual(result, "");
+  });
+
+  it("should handle empty or null input", () => {
+    assert.strictEqual(section("", "test"), "");
+    assert.strictEqual(section(null, "test"), null);
+    assert.strictEqual(section(undefined, "test"), undefined);
+  });
+
+  it("should handle missing section name", () => {
+    const content = `<!--section:intro-->Content`;
+
+    assert.strictEqual(section(content, ""), "");
+    assert.strictEqual(section(content, null), "");
+    assert.strictEqual(section(content, undefined), "");
+  });
+
+  it("should be case-insensitive for section names", () => {
+    const content = `<!--section:INTRO-->
+Content here
+<!--section:Main-->
+More content`;
+
+    const result1 = section(content, "intro");
+    const result2 = section(content, "INTRO");
+    const result3 = section(content, "main");
+    const result4 = section(content, "MAIN");
+
+    assert.strictEqual(result1, "\nContent here\n");
+    assert.strictEqual(result2, "\nContent here\n");
+    assert.strictEqual(result3, "\nMore content");
+    assert.strictEqual(result4, "\nMore content");
+  });
+
+  it("should handle multiple sections with the same name", () => {
+    const content = `<!--section:note-->
+First note
+<!--section:main-->
+Main content
+<!--section:note-->
+Second note
+<!--section:footer-->
+Footer`;
+
+    const result = section(content, "note");
+    assert.strictEqual(result, "\nFirst note\n\nSecond note\n");
+  });
+
+  it("should handle sections with no content", () => {
+    const content = `<!--section:empty--><!--section:main-->
+Main content`;
+
+    const result = section(content, "empty");
+    assert.strictEqual(result, "");
+  });
+
+  it("should handle content before first section", () => {
+    const content = `Some preamble
+<!--section:intro-->
+Intro content`;
+
+    const result = section(content, "intro");
+    assert.strictEqual(result, "\nIntro content");
+  });
+
+  it("should handle complex real-world example", () => {
+    const content = `# Document Title
+
+<!--section:summary,abstract-->
+This is a summary that can be used as an abstract.
+<!--section:introduction-->
+This is the introduction.
+<!--section:methods-->
+These are the methods.
+<!--section:conclusion,summary-->
+This is the conclusion and also part of summary.`;
+
+    const summary = section(content, "summary");
+    const introduction = section(content, "introduction");
+    const methods = section(content, "methods");
+    const conclusion = section(content, "conclusion");
+
+    assert.strictEqual(
+      summary,
+      "\nThis is a summary that can be used as an abstract.\n\nThis is the conclusion and also part of summary.",
+    );
+    assert.strictEqual(introduction, "\nThis is the introduction.\n");
+    assert.strictEqual(methods, "\nThese are the methods.\n");
+    assert.strictEqual(conclusion, "\nThis is the conclusion and also part of summary.");
+  });
+
+  it("should handle section markers with extra whitespace", () => {
+    const content = `<!--section: intro -->
+Content
+<!--section: main -->
+More`;
+
+    const result = section(content, "intro");
+    assert.strictEqual(result, "\nContent\n");
+  });
+});

package/src/index.js

@@ -1,4 +1,4 @@
-import { mdAutoRawTags, mdAutoNl2br, transformAutoRaw, transformNl2br } from "./transforms/markdown.js";
+import { mdAutoRawTags, mdAutoNl2br, transformAutoRaw, transformNl2br } from "./processors/markdown.js";
 import {
   autoLinkFavicons,
   isPlainUrlText,
@@ -6,13 +6,14 @@ import {
   buildFaviconLink,
   transformLink,
   replaceLinksInHtml,
-} from "./transforms/autoLinkFavicons.js";
+} from "./processors/autoLinkFavicons.js";
 import { attrSetFilter, attrSet } from "./filters/attr_set.js";
 import { attrIncludesFilter } from "./filters/attr_includes.js";
 import { mergeFilter, merge } from "./filters/merge.js";
 import { removeTagFilter, removeTag } from "./filters/remove_tag.js";
 import { ifFilter, iff } from "./filters/if.js";
 import { attrConcatFilter, attrConcat } from "./filters/attr_concat.js";
+import { sectionFilter, section as sectionFn } from "./filters/section.js";
 import { siteData } from "./siteData.js";
 
 // Conditionally import fetchFilter only if @11ty/eleventy-fetch is available
@@ -36,7 +37,7 @@ try {
  * @param {boolean} options.mdAutoRawTags - Enable mdAutoRawTags preprocessor (default: false)
  * @param {boolean} options.mdAutoNl2br - Enable mdAutoNl2br for \n to <br> conversion (default: false)
  * @param {boolean} options.autoLinkFavicons - Enable autoLinkFavicons to add favicons to plain text links (default: false)
- * @param {Array<string>} options.filters - Array of filter names to enable: 'attr_set', 'attr_includes', 'merge', 'remove_tag', 'if', 'attr_concat', 'fetch' (default: [])
+ * @param {Array<string>} options.filters - Array of filter names to enable: 'attr_set', 'attr_includes', 'merge', 'remove_tag', 'if', 'attr_concat', 'section', 'fetch' (default: [])
  * @param {boolean} options.siteData - Enable site.year and site.prod global data (default: false)
  */
 export default function eleventyBricksPlugin(eleventyConfig, options = {}) {
@@ -54,6 +55,7 @@ export default function eleventyBricksPlugin(eleventyConfig, options = {}) {
     remove_tag: removeTagFilter,
     if: ifFilter,
     attr_concat: attrConcatFilter,
+    section: sectionFilter,
     ...(fetchFilter && { fetch: fetchFilter }),
   };
 
@@ -86,6 +88,7 @@ export {
   removeTagFilter,
   ifFilter,
   attrConcatFilter,
+  sectionFilter,
   fetchFilter,
   siteData,
 };
@@ -104,4 +107,5 @@ export {
   iff,
   attrConcat,
   attrSet,
+  sectionFn as section,
 };