eleventy-plugin-asciidoc 5.0.0 → 5.1.0

package/README.md

@@ -35,14 +35,13 @@ module.exports = function (eleventyConfig) {
 };
 ```
 
-### Front Matter
+## 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._
 
-> [!NOTE]
-> 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.
+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/
@@ -69,9 +68,55 @@ 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).
 
-### Customize with Options
+### 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.
+
+## Options
+
+You can pass options as the second argument in `addPlugin()`.
+
+### Options for this plugin
+
+#### `eleventyAttributesPrefix`
+
+Default value is `eleventy-`.
+
+This config can be used to change the prefix string for [AsciiDoc style front matter](#front-matter).
+
+#### `resolveDocumentTitle`
+
+Default value is `false`.
+
+If enabled, the title will be resolved from the heading of the first section in the document. Otherwise, the title will be the Level 0 heading.
+
+```adoc
+== A second level heading
+
+This text is written in AsciiDoc format.
+```
+
+With `resolveDocumentTitle: true`, the above document will have a title (in page data). `A second level heading`.
+
+### Options for Asciidoctor.js
+
+All properties other than [the ones specific to the plugin](#options-for-this-plugin) will be passed to Asciidoctor.js.
 
-You can pass options to `convert()` of Asciidoctor.js as second argument in `addPlugin()`.
 These are the [available options](https://docs.asciidoctor.org/asciidoctor.js/latest/processor/convert-options/).
 
 ```js
@@ -126,12 +171,6 @@ 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/lib/eleventy-asciidoc.js

@@ -18,6 +18,7 @@ const processor = asciidoctor();
 /**
  * @typedef {Object} ExtraProcessorOptions
  * @property {string=} eleventyAttributesPrefix
+ * @property {Boolean} [resolveDocumentTitle=false]
  * @typedef {import('@asciidoctor/core').ProcessorOptions & ExtraProcessorOptions} EleventyAsciidocOptions
  */
 
@@ -31,6 +32,21 @@ const readFileSync = (inputPath) => {
   return matter(fs.readFileSync(inputPath, "utf8"));
 };
 
+/**
+ * Gets the title from ascii document document.
+ *
+ * @param      {object}   document         The document
+ * @param      {boolean}  [resolve=false]  The resolve
+ * @return     {string | undefined}   The title of the document.
+ */
+function getTitleFromAsciiDocDocument(document, resolve = false) {
+  if (resolve) {
+    return document.getDocumentTitle();
+  }
+
+  return document.getHeader()?.title;
+}
+
 /** @typedef {(inputPath: string) => Object.<string, any>} GetDataFn
  * Gets front-matter data from the file synchronously
  */
@@ -44,14 +60,19 @@ const readFileSync = (inputPath) => {
 
 const generateGetDataFromInputPath = (converterOptions) => (inputPath) => {
   const { content } = readFileSync(inputPath);
-  const { eleventyAttributesPrefix = "eleventy-" } = converterOptions;
+  const {
+    eleventyAttributesPrefix = "eleventy-",
+    resolveDocumentTitle = false,
+    ...restOfConverterOptions
+  } = converterOptions;
 
   const doc = processor.load(content, {
-    ...converterOptions,
-    base_dir: getBaseDir(inputPath, converterOptions.base_dir),
+    ...restOfConverterOptions,
+    base_dir: getBaseDir(inputPath, restOfConverterOptions.base_dir),
   });
 
-  const title = doc.getDocumentTitle();
+  const title = getTitleFromAsciiDocDocument(doc, resolveDocumentTitle);
+
   const attributes = doc.getAttributes();
 
   let eleventyAttributes = pickByKeyPrefix(
@@ -67,9 +88,11 @@ const generateGetDataFromInputPath = (converterOptions) => (inputPath) => {
   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 values

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-asciidoc",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Adds support for AsciiDoc to Eleventy",
   "main": "index.js",
   "funding": "https://github.com/sponsors/saneef/",