@anyblades/eleventy-blades 0.28.0-beta.2

package/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "printWidth": 120
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Staroverov 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+## <sub>Build Awesome /</sub><br> Eleventy blades <sup>![](https://img.shields.io/github/v/release/anyblades/eleventy-blades?label=&color=black)</sup>
+
+<!--section:summary-->
+
+Ultimate blade kit for 11ty (Build Awesome).
+
+<!--section:docs-->
+
+## Documentation
+
+<!--prettier-ignore-->
+- [Filters](              https://blades.ninja/build-awesome-11ty/filters/)
+  - [attr_concat](        https://blades.ninja/build-awesome-11ty/filters/#attr-concat),
+    [attr_includes](      https://blades.ninja/build-awesome-11ty/filters/#attr-includes),
+    [attr_set](           https://blades.ninja/build-awesome-11ty/filters/#attr-set)
+  - [date](               https://blades.ninja/build-awesome-11ty/filters/#date)
+  - [fetch](              https://blades.ninja/build-awesome-11ty/filters/#fetch) <!--{data-marker=🥷}-->
+  - [if](                 https://blades.ninja/build-awesome-11ty/filters/#if)
+  - [markdownify](        https://blades.ninja/build-awesome-11ty/filters/#markdownify)
+  - [merge](              https://blades.ninja/build-awesome-11ty/filters/#merge)
+  - [remove_tag](         https://blades.ninja/build-awesome-11ty/filters/#remove-tag),
+    [strip_tag](          https://blades.ninja/build-awesome-11ty/filters/#strip-tag)
+  - [section](            https://blades.ninja/build-awesome-11ty/filters/#section) <!--{data-marker=🥷}-->
+  - [unindent](           https://blades.ninja/build-awesome-11ty/filters/#unindent)
+- [Processors](           https://blades.ninja/build-awesome-11ty/processors/)
+  - [Auto link favicons]( https://blades.ninja/build-awesome-11ty/processors/#auto-link-favicons) <!--{data-marker=🥷}-->
+  - [Auto-raw tags](      https://blades.ninja/build-awesome-11ty/processors/#md-auto-raw)
+  - [Auto newlines-to-br](https://blades.ninja/build-awesome-11ty/processors/#md-auto-br)
+  - [Hidden markdown attrs<i>&nbsp;🆕</i>](https://blades.ninja/build-awesome-11ty/processors/#md-hidden-attrs) <!--{data-marker=🥷}-->
+- [Power tools](          https://blades.ninja/build-awesome-11ty/tools/)
+  - [Base config file](   https://blades.ninja/build-awesome-11ty/tools/#base-config) <!--{data-marker=🥷}-->
+  - [Base npm scripts](   https://blades.ninja/build-awesome-11ty/tools/#base-scripts) <!--{data-marker=🥷}-->
+  - [Data helpers](       https://blades.ninja/build-awesome-11ty/tools/#data-helpers)
+  - [Blades starters](    https://blades.ninja/build-awesome-11ty/tools/#starters) <!--{data-marker=🥷}-->
+
+<!--{.unlist .columns}-->
+
+---
+
+## Install
+
+<!--section:docs,install-->
+
+```sh
+npm install @anyblades/eleventy-blades
+```
+
+Then choose one of the following options:
+
+<mark>A. All-in</mark> managed by Eleventy Blades:
+
+Consider symlinking entire `eleventy.config.js` as a set-and-forget zero-config zero-maintenance solution:
+
+```sh
+ln -s ./node_modules/@anyblades/eleventy-blades/src/eleventy.config.js
+```
+
+Learn more: https://blades.ninja/11ty/tools/#base-config
+
+Living examples:
+
+- https://github.com/anyblades/build-awesome-starter
+- https://github.com/anyblades/bladeswitch
+
+<mark>B. Base config</mark> by Eleventy Blades with your additions/overrides in `eleventy.config.js`:
+
+```js
+import baseConfig from "@anyblades/eleventy-blades/base-config";
+
+export default function (eleventyConfig) {
+  baseConfig(eleventyConfig);
+
+  // Your additions/overrides
+  ...
+}
+```
+
+Living example: https://github.com/hostfurl/minformhf/blob/main/eleventy.config.js
+
+<mark>C. Plug-in</mark> Eleventy Blades in your existing `eleventy.config.js`:
+
+```js
+import eleventyBladesPlugin from "@anyblades/eleventy-blades";
+
+export default function (eleventyConfig) {
+  eleventyConfig.addPlugin(eleventyBladesPlugin, {
+    mdAutoRawTags: true,
+    mdAutoNl2br: true,
+    autoLinkFavicons: true,
+    siteData: true,
+    filters: ["attr_set", "attr_concat", ...],
+  });
+}
+```
+
+<mark>D. Individual imports</mark> from Eleventy Blades in your `eleventy.config.js`:
+
+```js
+import { siteData, mdAutoRawTags, mdAutoNl2br, autoLinkFavicons, attrSetFilter, attrConcatFilter, ... } from "@anyblades/eleventy-blades";
+
+export default function (eleventyConfig) {
+  siteData(eleventyConfig);
+  mdAutoRawTags(eleventyConfig);
+  mdAutoNl2br(eleventyConfig);
+  autoLinkFavicons(eleventyConfig);
+  attrSetFilter(eleventyConfig);
+  attrConcatFilter(eleventyConfig);
+  ...
+}
+```
+
+<div><hr></div>
+
+Or use a <mark>fully preconfigured template</mark> as an alternative option:
+
+<nav>
+
+[🥷 Build Awesome Starter ↗ &nbsp;<small style="white-space: nowrap">11ty + Tailwind + Typography + Blades</small>](https://github.com/anyblades/build-awesome-starter)<!--{role=button .outline}-->
+
+[🥷 Bladeswitch Starter ↗ &nbsp;<small style="white-space: nowrap">11ty + Pico + Blades</small>](https://github.com/anyblades/bladeswitch)<!--{role=button .outline}-->
+
+</nav>
+
+<!--section:docs-->
+
+---
+
+Featured by:
+
+- https://11tybundle.dev/blog/11ty-bundle-83/
+- https://11tybundle.dev/categories/getting-started/
+- https://hamatti.org/posts/markdown-content-split-to-sections-in-eleventy-and-nunjucks/#:~:text=anydigital
+- https://github.com/anydigital/awesome-11ty-build-awesome

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@anyblades/eleventy-blades",
+  "version": "0.28.0-beta.2",
+  "description": "A collection of helpful utilities and filters for Eleventy (11ty)",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    },
+    "./base-config": "./src/eleventy.config.js"
+  },
+  "scripts": {
+    "test": "node --test src/**/*.test.js",
+    "prepublishOnly": "npm run test"
+  },
+  "keywords": [
+    "11ty",
+    "eleventy",
+    "plugin",
+    "helpers",
+    "filters",
+    "markdown",
+    "nunjucks"
+  ],
+  "author": "Anton Staroverov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anyblades/eleventy-blades.git"
+  },
+  "bugs": {
+    "url": "https://github.com/anyblades/eleventy-blades/issues"
+  },
+  "homepage": "https://github.com/anyblades/eleventy-blades#readme",
+  "peerDependencies": {
+    "@11ty/eleventy": "^3.0.0 || ^4.0.0-alpha.6"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@11ty/lodash-custom": "^4.17.21"
+  }
+}

package/src/admin/index.html

@@ -0,0 +1,12 @@
+<!-- https://sveltiacms.app/en/docs/start#manual-installation -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="robots" content="noindex" />
+    <title>Sveltia CMS</title>
+  </head>
+  <body>
+    <script src="https://cdn.jsdelivr.net/npm/@sveltia/cms@0.128/dist/sveltia-cms.min.js"></script>
+  </body>
+</html>

package/src/do/README.md

@@ -0,0 +1,53 @@
+### Base 11ty npm scripts <small>via npm workspace</small> {#base-scripts}
+
+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.
+
+**Installation:**
+
+1. Install https://github.com/anyblades/eleventy-blades to reuse pre-defined 11ty scripts from there:
+
+```sh
+npm install @anyblades/eleventy-blades
+```
+
+2. Create a helper folder `do` to symlink the `do/package.json` within:
+
+```sh
+mkdir do
+cd ./do
+ln -s ../node_modules/@anyblades/eleventy-blades/src/do/package.json
+```
+
+3. Finally register `do` folder as npm workspace in your root `package.json`:
+
+```json {data-caption=./package.json}
+{
+  ...
+  "workspaces": ["do"],
+  "scripts": {
+    "start": "npm -w do run start",
+    "stage": "npm -w do run stage",
+    "build": "npm -w do run build"
+  },
+  ...
+}
+```
+
+**Done!** 🎉 Now you can run:
+
+- `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/anyblades/eleventy-blades/blob/main/src/do/package.json
+
+Living examples:
+
+- https://github.com/anyblades/build-awesome-starter
+- https://github.com/anyblades/bladeswitch
+
+**Benefits:**
+
+- **Clean separation**: Keep build scripts separate from project configuration
+- **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

package/src/do/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@anyblades/eleventy-blades-do",
+  "private": true,
+  "scripts": {
+    "build": "npm run tw && npm run 11ty -- $ELTY_OPTIONS",
+    "start": "npm run 11ty -- $ELTY_OPTIONS --serve --incremental & npm run tw -- --watch",
+    "prerestart": "npm run 11ty:clean",
+    "stage": "npm run 11ty:clean; npm run build && serve ../_site",
+    "11ty": "cd ../ && NODE_OPTIONS='--preserve-symlinks' eleventy",
+    "11ty:clean": "rm -r ../_site",
+    "11ty:debug": "DEBUG=* npm run 11ty --",
+    "tw": "cd ../ && tailwindcss -i ./_styles/styles.css -o ./_public/styles.css",
+    "tw:debug": "DEBUG=* npm run tw --"
+  }
+}

package/src/eleventy.config.js

@@ -0,0 +1,178 @@
+// <!--section:code-->```js
+
+/* Plugins */
+import { RenderPlugin } from "@11ty/eleventy";
+import eleventyBladesPlugin from "@anyblades/eleventy-blades";
+/* Dynamic plugins */
+let eleventyNavigationPlugin;
+try {
+  eleventyNavigationPlugin = (await import("@11ty/eleventy-navigation")).default;
+} catch (e) {
+  // @11ty/eleventy-navigation not installed
+}
+let pluginTOC;
+try {
+  pluginTOC = (await import("@uncenter/eleventy-plugin-toc")).default;
+} catch (e) {
+  // @uncenter/eleventy-plugin-toc not installed
+}
+let feedPlugin;
+try {
+  feedPlugin = (await import("@11ty/eleventy-plugin-rss")).feedPlugin;
+} catch (e) {
+  // @11ty/eleventy-plugin-rss not installed
+}
+/* Libraries */
+import markdownIt from "markdown-it";
+/* Dynamic libraries */
+let slugify;
+try {
+  slugify = (await import("@sindresorhus/slugify")).default;
+} catch (e) {
+  // @sindresorhus/slugify not installed
+}
+let markdownItAnchor;
+try {
+  markdownItAnchor = (await import("markdown-it-anchor")).default;
+} catch (e) {
+  // markdown-it-anchor not installed
+}
+let markdownItAttrs;
+try {
+  markdownItAttrs = (await import("markdown-it-attrs")).default;
+} catch (e) {
+  // markdown-it-attrs not installed
+}
+/* Data */
+import yaml from "js-yaml";
+import { readFileSync } from "node:fs";
+
+/**
+ * Eleventy Configuration
+ * @param {Object} eleventyConfig - The Eleventy configuration object
+ * @returns {Object} The Eleventy configuration object
+ */
+export default function (eleventyConfig) {
+  const inputDir = eleventyConfig.directories.input;
+
+  /* Jekyll parity */
+  eleventyConfig.addPassthroughCopy("assets");
+  eleventyConfig.addGlobalData("layout", "default");
+  eleventyConfig.setLiquidOptions({ dynamicPartials: false }); // allows unquoted Jekyll-style includes
+  eleventyConfig.addFilter("relative_url", (content) => content); // dummy
+
+  /* Plugins */
+  eleventyConfig.addPlugin(RenderPlugin);
+  if (eleventyNavigationPlugin) eleventyConfig.addPlugin(eleventyNavigationPlugin);
+  eleventyConfig.addPlugin(eleventyBladesPlugin, {
+    mdAutoNl2br: true,
+    mdAutoUncommentAttrs: true,
+    mdAutoRawTags: true,
+    autoLinkFavicons: true,
+    siteData: true,
+    filters: [
+      "attr_set",
+      "attr_includes",
+      "merge",
+      "remove_tag",
+      "if",
+      "attr_concat",
+      "fetch",
+      "section",
+      "strip_tag",
+      "unindent",
+      "date",
+    ],
+  });
+  if (pluginTOC) {
+    eleventyConfig.addPlugin(pluginTOC, {
+      ignoredElements: ["sub", "[data-is-anchor]"],
+      ul: true,
+      wrapper: (toc) => `<div data-is-toc>${toc}</div>`,
+    });
+  }
+  // https://www.11ty.dev/docs/plugins/rss/#virtual-template
+  if (feedPlugin) {
+    eleventyConfig.addCollection("feed", (collectionApi) => collectionApi.getAll().filter((item) => item.data.revised));
+    let siteData = {};
+    try {
+      siteData = yaml.load(readFileSync(`${inputDir}/_data/site.yml`, "utf8"));
+    } catch (e) {
+      // _data/site.yml not found
+    }
+    eleventyConfig.addPlugin(feedPlugin, {
+      type: "atom", // or "rss", "json"
+      outputPath: "/feed.xml",
+      collection: {
+        name: "feed", // iterate over `collections.posts`
+        limit: 100, // 0 means no limit
+      },
+      metadata: siteData,
+    });
+  }
+
+  /* Libraries */
+  let md = markdownIt({
+    html: true,
+    linkify: true,
+  });
+  if (markdownItAnchor) {
+    md = md.use(markdownItAnchor, {
+      slugify: slugify, // @TODO: TRICKS
+      permalink: markdownItAnchor.permalink.ariaHidden({
+        class: null,
+        renderAttrs: () => ({ "data-is-anchor": true }),
+      }),
+    });
+  }
+  if (markdownItAttrs) md = md.use(markdownItAttrs);
+  eleventyConfig.setLibrary("md", md);
+  eleventyConfig.addFilter("markdownify", (content) => md.render(String(content ?? "")));
+
+  /* Data */
+  eleventyConfig.addDataExtension("yml", (contents) => yaml.load(contents));
+
+  /* Build */
+  eleventyConfig.addPassthroughCopy(
+    {
+      _public: ".",
+      ...(inputDir !== "." && { [`${inputDir}/_public`]: "." }),
+    },
+    { expand: true }, // This follows/resolves symbolic links
+  );
+
+  /* Dev tools */
+  // Follow symlinks in Chokidar used by 11ty to watch files
+  eleventyConfig.setChokidarConfig({ followSymlinks: true });
+}
+/*```
+
+<!--section:docs-->
+### Base `eleventy.config.js` {#base-config}
+
+The package includes a fully-configured Eleventy config file `eleventy.config.js` that you can symlink to your project to get:
+
+- All eleventy-blades 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
+- Symlink support for development
+- _and more_
+
+**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
+
+**Installation as simple as:**
+
+```sh
+npm install @anyblades/eleventy-blades
+ln -s ./node_modules/@anyblades/eleventy-blades/src/eleventy.config.js
+```
+<!--section-->
+*/

package/src/filters/attr_concat.js

@@ -0,0 +1,107 @@
+// <!--section:code-->```js
+/**
+ * Concatenate values to an attribute array
+ *
+ * This function takes an object, an attribute name, and values to append.
+ * It returns a new object with the attribute as a combined array of unique items.
+ *
+ * @param {Object} obj - The object to modify
+ * @param {string} attr - The attribute name
+ * @param {Array|string|*} values - Values to concatenate (array, JSON string array, or single value)
+ * @returns {Object} A new object with the combined unique array
+ */
+export function attrConcat(obj, attr, values) {
+  // Get the existing attribute value, default to empty array if not present
+  const existingArray = obj?.[attr] || [];
+
+  // Check if existing value is an array, convert if not
+  if (!Array.isArray(existingArray)) {
+    console.error(`attrConcat: Expected ${attr} to be an array, got ${typeof existingArray}`);
+  }
+
+  // Process the values argument
+  let valuesToAdd = [];
+  if (Array.isArray(values)) {
+    valuesToAdd = values;
+  } else if (typeof values === "string" && values.length >= 2 && values.at(0) == "[" && values.at(-1) == "]") {
+    // Try to parse as JSON array
+    try {
+      const parsed = JSON.parse(values);
+      if (Array.isArray(parsed)) {
+        valuesToAdd = parsed;
+      } else {
+        valuesToAdd = [values];
+      }
+    } catch {
+      // Not valid JSON, treat as single value
+      valuesToAdd = [values];
+    }
+  } else {
+    // If it's a single value, wrap it in an array
+    valuesToAdd = [values];
+  }
+
+  // Combine arrays and remove duplicates using Set
+  const combinedArray = [...new Set([...existingArray, ...valuesToAdd])];
+
+  // Return a new object with the combined array
+  return {
+    ...obj,
+    [attr]: combinedArray,
+  };
+}
+
+/**
+ * attr_concat filter - Concatenate values to an attribute array
+ *
+ * This filter takes an object, an attribute name, and values to append.
+ * It returns a new object with the attribute as a combined array of unique items.
+ *
+ * @param {Object} eleventyConfig - The Eleventy configuration object
+ */
+export function attrConcatFilter(eleventyConfig) {
+  eleventyConfig.addFilter("attr_concat", attrConcat);
+}
+/*```
+
+<!--section:docs-->
+### `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.
+
+**Why use this?** When working with objects that have array attributes (like tags), you often need to add additional values without mutating the original object. The `attr_concat` filter provides a clean way to combine existing array values with new ones, automatically handling duplicates.
+
+**Features:**
+
+- Non-mutating: Creates a new object, leaving the original unchanged
+- Automatically removes duplicates using Set
+- Handles multiple input types: arrays, JSON string arrays (killer feature for `.liquid`), or single values
+- Creates the attribute as an empty array if it doesn't exist
+- Logs an error if the existing attribute is not an array
+- `TBC:` Supports nested attributes (e.g., `data.tags`)
+
+#### Example: Add tags to a post object in `.njk`:
+
+```jinja2
+{% set enhancedPost = post | attr_concat('tags', ['featured', 'popular']) %}
+```
+
+#### `PRO` Example: Add scripts and styles to the `site` object in `.liquid`:
+
+```liquid
+{% capture _ %}[
+  "https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism-tomorrow.min.css",
+  "https://cdn.jsdelivr.net/npm/prismjs@1/plugins/treeview/prism-treeview.min.css",
+  "https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@7/css/all.min.css",
+  "/styles.css"
+]{% endcapture %}
+{% assign site = site | attr_concat: 'styles', _ %}
+
+{% capture _ %}[
+  "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js",
+  "https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js",
+  "https://cdn.jsdelivr.net/npm/prismjs@1/plugins/treeview/prism-treeview.min.js"
+]{% endcapture %}
+{% assign site = site | attr_concat: 'scripts', _ %}
+```
+<!--section--> */