@anydigital/eleventy-bricks 0.26.0 → 0.27.0

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"],
 });
 ```
 
@@ -185,8 +190,9 @@ The plugin also exports the following utility functions for advanced usage:
 - `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-->
+<!--section:11ty-->
 
 ## Tricks from [Eleventy Bricks](https://github.com/anydigital/eleventy-bricks) {#eleventy-bricks}
 
@@ -208,6 +214,7 @@ The plugin also exports the following utility functions for advanced usage:
 | {.divider} | Textual                                                                        |
 |  `HTML \|` | `striptags`                                                                    | `strip_html`                                         |
 |  `HTML \|` | [`remove_tag(TAG)`](#remove_tag)                                               | [`remove_tag: TAG`](#remove_tag)                     |
+|  `HTML \|` | [`section(NAME)`](#section)                                                    | [`section: NAME`](#section)                          |
 |   `STR \|` | `remove: STR2`                                                                 | `remove: STR2`                                       |
 | {.divider} | Other                                                                          |
 |   `URL \|` | [`fetch`](#fetch)                                                              | [`fetch`](#fetch)                                    |
@@ -520,6 +527,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
+
+&lt;!--section:intro-->
+
+This is the introduction that appears at the top of the page.
+
+&lt;!--section:main-->
+
+This is the main body of the post with all the details.
+
+&lt;!--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: `&lt;!--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 `&lt;!--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: `&lt;!--section:NAME-->` or `&lt;!--section:NAME1,NAME2-->`
+- Sections end at the next `&lt;!--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.
@@ -1101,6 +1205,8 @@ mkdir -p admin
 ln -s ../node_modules/@anydigital/eleventy-bricks/src/admin/index.html admin/index.html
 ```
 
+<!--section:npm,11ty-->
+
 ### 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.

package/examples/section-filter.md

@@ -0,0 +1,96 @@
+# Section Filter Examples
+
+## Basic Usage
+
+```markdown
+<!--section:intro-->
+
+This is the introduction section.
+
+<!--section:main-->
+
+This is the main content.
+
+<!--section:footer-->
+
+This is the footer.
+```
+
+In your template:
+
+```nunjucks
+{{ content | section('intro') }}
+```
+
+Output:
+
+```
+This is the introduction section.
+```
+
+## Multiple Names per Section
+
+```markdown
+<!--section:summary,abstract-->
+
+This content appears in both 'summary' and 'abstract' sections.
+
+<!--section:conclusion-->
+
+Final thoughts.
+```
+
+Both of these work:
+
+```nunjucks
+{{ content | section('summary') }}
+{{ content | section('abstract') }}
+```
+
+## Real-World Example
+
+```markdown
+# Research Paper
+
+<!--section:abstract,summary-->
+
+A brief overview of the research findings.
+
+<!--section:introduction-->
+
+Background and context for the research.
+
+<!--section:methodology-->
+
+How the research was conducted.
+
+<!--section:results-->
+
+Key findings from the study.
+
+<!--section:conclusion,summary-->
+
+Summary and implications of the research.
+```
+
+Usage:
+
+```nunjucks
+<!-- Get full summary (abstract + conclusion) -->
+<div class="summary">
+  {{ content | section('summary') }}
+</div>
+
+<!-- Get just introduction -->
+<div class="intro">
+  {{ content | section('introduction') }}
+</div>
+```
+
+## Notes
+
+- Section names are **case-insensitive**: `intro`, `INTRO`, and `Intro` are all the same
+- Multiple names can be comma-separated: `<!--section:name1,name2,name3-->`
+- Whitespace around names is trimmed
+- Content extends from the section marker to the next `<!--section*>` or EOF
+- If a section name appears multiple times, all matching sections are concatenated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anydigital/eleventy-bricks",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "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

@@ -13,6 +13,7 @@ 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,
 };