eleventy-plugin-asciidoc 5.0.0-alpha.1 → 5.0.1

package/README.md

@@ -25,7 +25,7 @@ npm install eleventy-plugin-asciidoc
 
 ### Add to Configuration File
 
-Usually `.eleventy.js`:
+Usually `eleventy.config.js` or `.eleventy.js`:
 
 ```js
 const eleventyAsciidoc = require("eleventy-plugin-asciidoc");
@@ -35,6 +35,58 @@ module.exports = function (eleventyConfig) {
 };
 ```
 
+### Front Matter
+
+You can use either [Eleventy style front matter](https://www.11ty.dev/docs/data-frontmatter/#front-matter-formats) or AsciiDoc document attributes to write front matter.
+
+Any AsciiDoc document attributes that are prefixed with `eleventy-` ([configurable](#eleventyAttributesPrefix)) can be used as front matter. _The prefix, `eleventy-`, will be removed from variable names available in the templates._
+
+Only document-scoped attributes or variables can be used for front matter. Attributes that are written after the document title (`= Document Title`) will not be considered for front matter.
+
+```adoc
+:eleventy-permalink: /hello-world/
+:eleventy-layout: base.njk
+
+= Hello World
+
+Hello everyone!
+```
+
+The above AsciiDoc attribute front matter is the same as YAML based front matter below:
+
+```adoc
+---
+permalink: /hello-world/
+layout: base.njk
+---
+
+= Hello World
+
+Hello everyone!
+```
+
+> [!WARNING]
+> Asciidoctor.js converts all attribute names to lower case letters. Example `:eleventy-aTitle:` will be made available as `atitle` in front matter data (also as `eleventy-atitle` in document attributes).
+
+#### Data Cascade
+
+Data specified using AsciiDoc style front matter override YAML (or front matter in other Eleventy supported formats).
+
+```adoc
+---
+layout: layout-a.njk
+---
+:eleventy-layout: layout-b.njk
+
+= Hello World
+
+Hello everyone!
+```
+
+In the above case, front matter data will have `{ layout: layout-b.njk }`.
+
+In the case of `title`, [the AsciiDoc document title](https://docs.asciidoctor.org/asciidoc/latest/document/title/) (including `title` and `doctitle` attributes) takes precedence over front matter.
+
 ### Customize with Options
 
 You can pass options to `convert()` of Asciidoctor.js as second argument in `addPlugin()`.
@@ -92,6 +144,12 @@ module.exports = function (eleventyConfig) {
 
 Refer to [Asciidoctor.js documentation](https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/) to know more about extensions.
 
+#### `eleventyAttributesPrefix`
+
+Default value is `eleventy-`.
+
+This config can be used to change the prefix string for [AsciiDoc style front matter](#front-matter).
+
 ### CSS Styles
 
 The plugin does not include any CSS styles. It is up to you to style the content.

package/{.eleventy.js → index.js}

@@ -2,14 +2,14 @@
 const eleventyAsciidoc = require("./lib/eleventy-asciidoc.js");
 const pkg = require("./package.json");
 
-/** @typedef {import('./lib/eleventy-asciidoc.js').ProcessorOptions} ProcessorOptions} */
+/** @typedef {import('./lib/eleventy-asciidoc.js').EleventyAsciidocOptions} EleventyAsciidocOptions} */
 
 module.exports = {
   /**
    * Plugin config function
    *
    * @param      {object}            eleventyConfig     The eleventy configuration object
-   * @param      {ProcessorOptions}  converterOptions   Options for Asciidoctor.converter()
+   * @param      {EleventyAsciidocOptions}  converterOptions   Options for Asciidoctor.converter()
    */
   configFunction(eleventyConfig, converterOptions) {
     try {

package/lib/eleventy-asciidoc.js

@@ -7,7 +7,8 @@ const fs = require("fs");
 const matter = require("gray-matter");
 const path = require("path");
 const nunjucks = require("nunjucks");
-const { parseDocumentAttributes, pickByKeyPrefix } = require("./utils.js");
+const { parseDocumentAttributes } = require("./utils/asciidoc.js");
+const { pickByKeyPrefix, mapKeys, pick } = require("./utils/object.js");
 
 // @ts-ignore
 const processor = asciidoctor();
@@ -52,26 +53,30 @@ const generateGetDataFromInputPath = (converterOptions) => (inputPath) => {
 
   const title = doc.getDocumentTitle();
   const attributes = doc.getAttributes();
-  const eleventyAttributes = pickByKeyPrefix(
+
+  let eleventyAttributes = pickByKeyPrefix(
     attributes,
     eleventyAttributesPrefix,
   );
+  eleventyAttributes = mapKeys(eleventyAttributes, (k) =>
+    k.slice(eleventyAttributesPrefix.length),
+  );
 
   debug(`Document title ${title}`);
   debug(`Document attributes: ${JSON.stringify(attributes)}`);
   debug(`Document Eleventy attributes: ${JSON.stringify(eleventyAttributes)}`);
 
   let data = {
-    title,
     asciidocAttributes: attributes,
     ...eleventyAttributes,
+    // Pass title only if defined. Otherwise, `undefined`
+    // will override the title in `eleventyAttributes`
+    ...(title === undefined ? {} : { title }),
   };
 
-  // Removes undefined or null values
+  // Removes undefined values
   // that may override Eleventy page data.
-  data = Object.entries(data)
-    .filter((v) => Boolean(v[1]))
-    .reduce((acc, [k, v]) => ({ ...acc, [k]: v }), {});
+  data = pick(data, (k, v) => v !== undefined);
 
   return {
     data,

package/lib/utils/asciidoc.js

@@ -0,0 +1,25 @@
+// @ts-check
+
+/** @typedef {import('@asciidoctor/core').Attributes} Attributes */
+
+/**
+ * Parses AsciiDoc Document attributes into object
+ *
+ * @param      {Attributes | string[] | string}  attrs    AsciiDoc Document Attributes
+ * @return     {Attributes}  Attributes as Object
+ */
+function parseDocumentAttributes(attrs) {
+  if (Array.isArray(attrs)) {
+    return Object.fromEntries(attrs.map((a) => a.split("=")));
+  }
+
+  if (typeof attrs === "string") {
+    return Object.fromEntries([attrs.split("=")]);
+  }
+
+  return attrs;
+}
+
+module.exports = {
+  parseDocumentAttributes,
+};

package/lib/{utils.js → utils/object.js}

@@ -1,25 +1,5 @@
 // @ts-check
 
-/** @typedef {import('@asciidoctor/core').Attributes} Attributes */
-
-/**
- * Parses AsciiDoc Document attributes into object
- *
- * @param      {Attributes | string[] | string}  attrs    AsciiDoc Document Attributes
- * @return     {Attributes}  Attributes as Object
- */
-function parseDocumentAttributes(attrs) {
-  if (Array.isArray(attrs)) {
-    return Object.fromEntries(attrs.map((a) => a.split("=")));
-  }
-
-  if (typeof attrs === "string") {
-    return Object.fromEntries([attrs.split("=")]);
-  }
-
-  return attrs;
-}
-
 /**
  * Return a copy of the object, filtered to only have values for the allowed keys (or array of valid keys). Alternatively accepts a predicate indicating which keys to pick.
  *
@@ -27,7 +7,7 @@ function parseDocumentAttributes(attrs) {
  * @param      {(key: string, value: any, obj: object ) => boolean | Array<string>}  keys    The keys
  * @return     {object}  Copy of the object with filtered values
  */
-function pick(obj, keys = (k) => Boolean(k)) {
+function pick(obj, keys = (_k, v) => Boolean(v)) {
   if (Array.isArray(keys)) {
     return pick(obj, (key) => keys.includes(key));
   }
@@ -52,17 +32,28 @@ function pick(obj, keys = (k) => Boolean(k)) {
  * @return     {object}  Copy of the object with filtered values
  */
 function pickByKeyPrefix(obj, prefix) {
-  const filteredObj = pick(obj, (k) => k.startsWith(prefix));
-  return Object.entries(filteredObj).reduce((acc, [k, v]) => {
+  return pick(obj, (k) => k.startsWith(prefix));
+}
+
+/**
+ * Creates a copy of of the object keys generated by running mapKey
+ *
+ * @param      {object}    obj                 The object
+ * @param      {(k: string, v: any)=> string}  [mapKey=(k)=>k]  The function to map the keys
+ * @return     {object}    { Copy of the object with mapped keys }
+ */
+function mapKeys(obj, mapKey = (k) => k) {
+  return Object.entries(obj).reduce((acc, [k, v]) => {
+    const newKey = mapKey(k, v);
     return {
-      [k.slice(prefix.length)]: v,
+      [newKey]: v,
       ...acc,
     };
   }, {});
 }
 
 module.exports = {
-  parseDocumentAttributes,
   pickByKeyPrefix,
   pick,
+  mapKeys,
 };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "eleventy-plugin-asciidoc",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.1",
   "description": "Adds support for AsciiDoc to Eleventy",
-  "main": ".eleventy.js",
+  "main": "index.js",
   "funding": "https://github.com/sponsors/saneef/",
   "repository": {
     "type": "git",
@@ -23,7 +23,7 @@
   "author": "Saneef Ansari <hello@saneef.com> (https://saneef.com/)",
   "license": "MIT",
   "11ty": {
-    "compatibility": ">=1.0.0"
+    "compatibility": ">=2.0.0-canary.19"
   },
   "dependencies": {
     "@asciidoctor/core": "^3.0.4",
@@ -45,7 +45,7 @@
     "rimraf": "^6.0.1"
   },
   "lint-staged": {
-    "*.js": "eslint --cache --fix --ignore-pattern \"!.eleventy.js\"",
+    "*.{js,mjs,cjs}": "eslint --cache --fix",
     "*.{js,md,json}": "prettier --write"
   },
   "ava": {