@d10f/asciidoc-astro-loader 0.0.2 → 0.0.4

package/README.md

@@ -8,39 +8,39 @@ This package will allow you to load Asciidoc files (with either an `.asciidoc` o
 - [x] Support for custom templating engines.
 - [x] Support for custom converters for maximum control over the output HTML.
 - [x] Full TypeScript support.
+- [x] Restructure configuration options regarding Shiki transformer integration.
 
 ## Roadmap
 
 - [ ] Async support on custom template and converter class render methods.
 - [ ] Include support for more template engines out of the box.
-- [ ] Restructure configuration options regarding Shiki transformer integration.
 
 ## Getting Started
 
-1. Install the loader from `npm`:
+Install the package from `npm`:
 
    ```console
    npm install @d10f/asciidoc-astro-loader
    ```
 
-1. Import and run the loader function inside your `content.config.ts` file to define a new collection:
+And import the loader function inside your `content.config.ts` file to define a new collection:
 
-    ```ts
-    import { defineCollection, z } from "astro:content";
-    import { asciidocLoader } from "asciidoc-astro-loader";
+```ts
+import { defineCollection, z } from "astro:content";
+import { asciidocLoader } from "asciidoc-astro-loader";
 
-    const blog = defineCollection({
-        loader: asciidocLoader({
-            base: ".src/content/blog",
-        }),
-        schema: z.object({
-            title: z.string(),
-            preamble: z.string().optional(),
-            createdAt: z.coerce.date(),
-            updatedAt: z.coerce.date().optional(),
-        }),
-    });
-    ```
+const blog = defineCollection({
+    loader: asciidocLoader({
+        base: ".src/content/blog",
+    }),
+    schema: z.object({
+        title: z.string(),
+        preamble: z.string().optional(),
+        createdAt: z.coerce.date(),
+        updatedAt: z.coerce.date().optional(),
+    }),
+});
+```
 
 
 ## Configuration
@@ -64,15 +64,15 @@ You can specify an object for different light and dark themes, as well:
 
 ```ts
 const blog = defineCollection({
-	loader: asciidocLoader({
-		base: ".src/content/blog",
-		syntaxHighlighting: {
-			theme: {
-				light: "everforest-light",
-				dark: "everforest-dark",
-			},
-		}
-	}),
+    loader: asciidocLoader({
+        base: ".src/content/blog",
+        syntaxHighlighting: {
+            theme: {
+                light: "everforest-light",
+                dark: "everforest-dark",
+            },
+        }
+    }),
 });
 ```
 
@@ -80,16 +80,16 @@ And even provide additional themes. Note that you will have to take care of impl
 
 ```ts
 const blog = defineCollection({
-	loader: asciidocLoader({
-		base: ".src/content/blog",
-		syntaxHighlighting: {
-			theme: {
-				light: "gruvbox-light-hard",
-				dark: "gruvbox-dark-hard",
-				dim: "gruvbox-dark-medium"
-			},
-		}
-	}),
+    loader: asciidocLoader({
+        base: ".src/content/blog",
+        syntaxHighlighting: {
+            theme: {
+                light: "gruvbox-light-hard",
+                dark: "gruvbox-dark-hard",
+                dim: "gruvbox-dark-medium"
+            },
+        }
+    }),
 });
 ```
 
@@ -99,26 +99,66 @@ One of the coolest features from Shiki are [transformers](https://shiki.style/gu
 
 ```ts
 import {
-	transformerNotationDiff,
-	transformerNotationFocus,
-	transformerNotationHighlight,
+    transformerNotationDiff,
+    transformerNotationFocus,
+    transformerNotationHighlight,
 } from '@shikijs/transformers';
 
 const blog = defineCollection({
-	loader: asciidocLoader({
-		base: ".src/content/blog",
-		syntaxHighlighting: {
-			transformers: [
-				transformerNotationDiff(),
-				transformerNotationHighlight(),
-				transformerNotationFocus(),
-			],
-		}
-	}),
+    loader: asciidocLoader({
+        base: ".src/content/blog",
+        syntaxHighlighting: {
+            transformers: [
+                transformerNotationDiff(),
+                transformerNotationHighlight(),
+                transformerNotationFocus(),
+            ],
+        }
+    }),
 });
 ```
 
-These transformers from the example above are already used by default, simply because I use them frequently, so this example is redundant and only for illustration purposes. Providing an array here will overwrite these defaults, however.
+If you want to write your own transformers, you can just follow Shiki's documentation and provide them here. However, you might also be interested in performing some conditional logic based on the type of Asciidoc node you're working with. To gain access to the node, define the transformer as a factory function using the `ShikiTransformerFactory` type:
+
+```typescript
+import type { ShikiTransformerFactory } from '../../../types/index.js';
+
+type TranformerOptions = {
+    cssClasses: string;
+};
+
+export const transformerAsciidocSomething: ShikiTransformerFactory<
+    TransformerOptions
+> = ({ cssClasses }) => {
+    return (node) => {
+        return {
+            preprocess() {
+                if (node.getAttribute('custom-attribute')) {
+                    // Maybe you only want to do something based on
+                    // some custom attribute?
+                }
+            }
+        }
+    }
+}
+```
+
+```ts
+import { transformerAsciidocSomething } from './usr/share/transformers';
+
+const blog = defineCollection({
+    loader: asciidocLoader({
+        base: ".src/content/blog",
+        syntaxHighlighting: {
+            transformers: [
+                transformerAsciidocSomethign({
+                    cssClasses: 'text-red-500'
+                }),
+            ],
+        }
+    }),
+});
+```
 
 ## Custom Templates
 
@@ -126,12 +166,12 @@ A nice feature of Asciidoctor.js is the use of default templates for rendering t
 
 ```ts
 const blog = defineCollection({
-	loader: asciidocLoader({
-		base: ".src/content/blog",
-		document: {
-			template: "./usr/share/templates"
-		}
-	}),
+    loader: asciidocLoader({
+        base: ".src/content/blog",
+        document: {
+            template: "./usr/share/templates"
+        }
+    }),
 });
 ```
 
@@ -162,7 +202,7 @@ export class PhpEngine extends AbstractEngine implements AsciidocTemplate, Files
     /**
      * This method is enforced by the FilesystemTemplate interface.
      */
-	renderFile(filepath: string, options?: Record<string, unknown>) {}
+    renderFile(filepath: string, options?: Record<string, unknown>) {}
 }
 ```
 
@@ -177,15 +217,15 @@ When your engine is ready, you can import it and pass it to the loader configura
 import { PhpEngine } from './usr/share/engines';
 
 const blog = defineCollection({
-	loader: asciidocLoader({
-		base: ".src/content/blog",
-		document: {
-			template: "./usr/share/templates",
-			templateEngines: [
-				New PhpEngine({ name: 'php', extensions: ['php'], root: './usr/share/templates' })
-			],
-		}
-	}),
+    loader: asciidocLoader({
+        base: ".src/content/blog",
+        document: {
+            template: "./usr/share/templates",
+            templateEngines: [
+                New PhpEngine({ name: 'php', extensions: ['php'], root: './usr/share/templates' })
+            ],
+        }
+    }),
 });
 ```
 
@@ -197,40 +237,40 @@ import { AbstractEngine } from '@d10f/asciidoc-astro-loader/engines';
 
 import type { AbstractBlock } from 'asciidoctor';
 import type {
-	AsciidocTemplate,
-	FilesystemTemplate,
-	NodeContext
+    AsciidocTemplate,
+    FilesystemTemplate,
+    NodeContext
 } from '@d10f/asciidoc-astro-loader';
 
 export class PhpEngine extends AbstractEngine implements AsciidocTemplate, FilesystemTemplate {
-	private server: Php;
+    private server: Php;
 
     constructor({ name = 'php', extensions = ['php'], root: string }) {
         super(name, extensions);
         this.server = new Php({ docroot: root });
     }
 
-	renderNode(node: AbstractBlock, options?: Record<string, unknown>) {
-		const context = node.getNodeName() as NodeContext;
-		const content = node.getContent();
-		const templateFile = this.templateList.get(context);
-
-		if (templateFile) {
-			const filepath = templateFile.replace(/^.+\/(.+)$/, '$1');
-			return this.renderFile(filepath, { content });
-		}
-	}
-
-	renderFile(filepath: string, options?: Record<string, unknown>): string {
-		const request = new Request({
-			method: 'POST',
-			url: 'http://localhost/' + filepath,
-			body: Buffer.from(JSON.stringify(options)),
-		});
-
-		const response = this.server.handleRequestSync(request);
-		return response.body.toString();
-	}
+    renderNode(node: AbstractBlock, options?: Record<string, unknown>) {
+        const context = node.getNodeName() as NodeContext;
+        const content = node.getContent();
+        const templateFile = this.templateList.get(context);
+
+        if (templateFile) {
+            const filepath = templateFile.replace(/^.+\/(.+)$/, '$1');
+            return this.renderFile(filepath, { content });
+        }
+    }
+
+    renderFile(filepath: string, options?: Record<string, unknown>): string {
+        const request = new Request({
+            method: 'POST',
+            url: 'http://localhost/' + filepath,
+            body: Buffer.from(JSON.stringify(options)),
+        });
+
+        const response = this.server.handleRequestSync(request);
+        return response.body.toString();
+    }
 }
 ```
 
@@ -250,16 +290,33 @@ Custom converters are refined versions of templates. The main difference is that
 
 For maximum flexibility, both custom converters and templates can be used at the same time. You can even define templates that aren't designed to be used to render nodes directly, but called directly from within your custom converters. This is why the use of interfaces when defining custom templates is important, to ensure consistency and type-safety.
 
-In general, prefer using converters for anything that requires heavy use of logic, and templates for simpler HTML output.
+In general, prefer using converters for anything that requires heavy use of logic or that reads configuration options provided by the user, and templates for simpler HTML output.
+
+Custom converters are provided as an array to the `document.converters` option.
+
+```ts
+// src/content.config.ts
+
+const blog = defineCollection({
+    loader: asciidocLoader({
+        base: ".src/content/blog",
+        document: {
+            converters: [
+                myCustomConverter({ /* ... */ })
+            ]
+        },
+    }),
+});
+```
 
 ### Registering a custom converter
 
-A custom converter is declared as a factory function that returns another function. This allows you to provide whatever configuration options you want when registering this converter in the loader configuration.
+A custom converter is declared as a factory function that accepts a configuration object, and returns an inner function that gets called automatically, receiving the options provided to the loader and the instance of the Shiki highlighter.
 
 ```ts
 import type { CustomConverterFactoryFn, NodeContext } from '@d10f/asciidoc-astro-loader';
 
-export const customConverter: CustomConverterFactoryFn = ({ nodeContext }) => {
+export const myCustomConverter: CustomConverterFactoryFn = ({ nodeContext }) => {
     return (options, highlighter) => {
         return {
 
@@ -284,3 +341,4 @@ export const customConverter: CustomConverterFactoryFn = ({ nodeContext }) => {
 }
 ```
 
+In addition, the `convert` method receives the node that is being processed, as well as an instance of the template engine registry. You can use this to render the HTML from a template as well, combining both to get the best of both worlds.

package/dist/chunk-2UGTFP4R.js

@@ -0,0 +1,22 @@
+// src/lib/utils.ts
+function slugify(text) {
+  return text.trim().normalize().toLowerCase().replace(/\s+/g, "-").replace(/[^\w-]+/g, "").replace(/--+/g, "-").replace(/^-+/, "").replace(/-+$/, "");
+}
+function escapeRegexCharacters(str) {
+  const re = /[-\\^$*+?.()|\[\]{}]/g;
+  return str.replace(re, "\\$&");
+}
+function splitFilenameComponents(filename) {
+  const match = filename.match(/^(?<path>.*\/)*(?<name>[^\.]+)\.(?<ext>.*)$/);
+  return {
+    filepath: match?.groups?.path ?? null,
+    filename: match?.groups?.name ?? null,
+    extension: match?.groups?.ext ?? null
+  };
+}
+
+export {
+  slugify,
+  escapeRegexCharacters,
+  splitFilenameComponents
+};

package/dist/chunk-5P6LDJGO.js

@@ -0,0 +1,65 @@
+import {
+  escapeRegexCharacters
+} from "./chunk-2UGTFP4R.js";
+
+// src/lib/shiki/transformers/transformAsciidocCallout.ts
+var transformAsciidocCallout = (options) => {
+  return (node) => {
+    const lineComments = ["//", "#", ";;"];
+    const customLineComment = node.getAttribute("line-comment");
+    if (customLineComment) {
+      lineComments.push(escapeRegexCharacters(customLineComment));
+    }
+    const calloutReList = [
+      // Handles C-style and similar comments like Perl, Python...
+      new RegExp(`\\s+(?:${lineComments.join("|")})((?:\\s+<(\\d+)>)+)`),
+      // Handles XML comments
+      new RegExp(/((?:\s*<!--(\d+)-->)+)/)
+    ];
+    const commentTokensRe = new RegExp(
+      `(?:${lineComments.join("|")}|<!--|-->|[<>])`,
+      "g"
+    );
+    const linesWithCallout = {};
+    return {
+      preprocess(code) {
+        return code.split("\n").map((line, idx) => {
+          for (const re of calloutReList) {
+            const match = line.match(re);
+            if (!match) continue;
+            const callouts = match[0].replaceAll(commentTokensRe, "").trim().split(" ");
+            linesWithCallout[idx + 1] = callouts;
+            return line.replace(re, "");
+          }
+          return line;
+        }).join("\n");
+      },
+      line(hast, line) {
+        const callouts = linesWithCallout[line];
+        if (!callouts) return;
+        callouts.forEach((calloutId) => {
+          hast.properties[`data-callout-${calloutId}`] = "";
+          hast.children.push({
+            type: "element",
+            tagName: "span",
+            properties: {
+              class: options?.cssClasses ?? "conum",
+              style: options?.cssClasses ? "" : "user-select:none; pointer-events:none; opacity:0.5; margin-inline:8px;",
+              "data-value": calloutId
+            },
+            children: [
+              {
+                type: "text",
+                value: calloutId
+              }
+            ]
+          });
+        });
+      }
+    };
+  };
+};
+
+export {
+  transformAsciidocCallout
+};

package/dist/{chunk-BRMWIQA2.js → chunk-NC6IZHLR.js}

@@ -1,12 +1,12 @@
 import {
-  splitFilenameComponents,
-  transformAsciidocCallout,
-  transformConsoleCodeBlock
-} from "./chunk-DDIUST2Z.js";
+  splitFilenameComponents
+} from "./chunk-2UGTFP4R.js";
 
 // src/lib/asciidoc/converters/sourceCodeConverter.ts
 import { resolve } from "path";
-var sourceCodeConverter = ({ transformers, template }) => {
+var sourceCodeConverter = (converterOptions) => {
+  const transformers = converterOptions?.transformers;
+  const template = converterOptions?.template;
   return (options, highlighter) => {
     return {
       nodeContext: "listing",
@@ -17,11 +17,9 @@ var sourceCodeConverter = ({ transformers, template }) => {
         const output = highlighter.codeToHtml(input, {
           ...options.syntaxHighlighting,
           lang,
-          transformers: [
-            ...transformers ?? [],
-            transformAsciidocCallout({ node }),
-            transformConsoleCodeBlock()
-          ]
+          transformers: (transformers ?? []).map((transformer) => {
+            return typeof transformer === "function" ? transformer(node) : transformer;
+          })
         });
         if (templateEngine && template) {
           const { extension } = splitFilenameComponents(template);