@d10f/asciidoc-astro-loader 0.0.3 → 0.0.4

package/README.md

@@ -290,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 {
 
@@ -324,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-KZRXEKZK.js → chunk-NC6IZHLR.js}

@@ -4,7 +4,9 @@ import {
 
 // 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",

package/dist/{index-sFlXF8Qm.d.cts → index-CS3PBqxf.d.cts}

@@ -333,6 +333,22 @@ declare class TemplateEngineRegistry {
     private loadTemplates;
 }
 
+/**
+ * Checks if the given property K is required in object T.
+ *
+ * @credit Chris Cook
+ * @see https://zirkelc.dev/posts/typescript-how-to-check-for-optional-properties
+ */
+type IsRequired<T, K extends keyof T> = undefined extends T[K] ? object extends Pick<T, K> ? false : true : true;
+/**
+ * Checks if any of the properties in T are required.
+ *
+ * @credit Chris Cook
+ * @see https://zirkelc.dev/posts/typescript-how-to-check-for-optional-properties
+ */
+type HasRequiredKeys<T extends object> = keyof {
+    [K in keyof T as IsRequired<T, K> extends true ? K : never]: T[K];
+} extends never ? false : true;
 type CustomConverter = {
     /**
      * The node context, or node type, that this converter will act upon.
@@ -353,9 +369,9 @@ type CustomConverter = {
      */
     convert(node: AbstractNode, templateEngine?: TemplateEngineRegistry): string | null | undefined;
 };
-type CustomConverterFactoryFn<T extends object | undefined> = (converterOptions: T) => CustomConverterFn;
+type CustomConverterFactoryFn<T extends object> = HasRequiredKeys<T> extends true ? (converterOptions: T) => CustomConverterFn : (converterOptions?: T) => CustomConverterFn;
 type CustomConverterFn = (opts: RequiredOptions, highlighter: HighlighterCore) => CustomConverter;
-type ShikiTransformerFactory<T extends object> = (options?: T) => ShikiTransformerFactoryFn;
+type ShikiTransformerFactory<T extends object> = HasRequiredKeys<T> extends true ? (options: T) => ShikiTransformerFactoryFn : (options?: T) => ShikiTransformerFactoryFn;
 type ShikiTransformerFactoryFn = (node: AbstractNode) => ShikiTransformer;
 type CalloutOptions = Partial<{
     /**

package/dist/{index-sFlXF8Qm.d.ts → index-CS3PBqxf.d.ts}

@@ -333,6 +333,22 @@ declare class TemplateEngineRegistry {
     private loadTemplates;
 }
 
+/**
+ * Checks if the given property K is required in object T.
+ *
+ * @credit Chris Cook
+ * @see https://zirkelc.dev/posts/typescript-how-to-check-for-optional-properties
+ */
+type IsRequired<T, K extends keyof T> = undefined extends T[K] ? object extends Pick<T, K> ? false : true : true;
+/**
+ * Checks if any of the properties in T are required.
+ *
+ * @credit Chris Cook
+ * @see https://zirkelc.dev/posts/typescript-how-to-check-for-optional-properties
+ */
+type HasRequiredKeys<T extends object> = keyof {
+    [K in keyof T as IsRequired<T, K> extends true ? K : never]: T[K];
+} extends never ? false : true;
 type CustomConverter = {
     /**
      * The node context, or node type, that this converter will act upon.
@@ -353,9 +369,9 @@ type CustomConverter = {
      */
     convert(node: AbstractNode, templateEngine?: TemplateEngineRegistry): string | null | undefined;
 };
-type CustomConverterFactoryFn<T extends object | undefined> = (converterOptions: T) => CustomConverterFn;
+type CustomConverterFactoryFn<T extends object> = HasRequiredKeys<T> extends true ? (converterOptions: T) => CustomConverterFn : (converterOptions?: T) => CustomConverterFn;
 type CustomConverterFn = (opts: RequiredOptions, highlighter: HighlighterCore) => CustomConverter;
-type ShikiTransformerFactory<T extends object> = (options?: T) => ShikiTransformerFactoryFn;
+type ShikiTransformerFactory<T extends object> = HasRequiredKeys<T> extends true ? (options: T) => ShikiTransformerFactoryFn : (options?: T) => ShikiTransformerFactoryFn;
 type ShikiTransformerFactoryFn = (node: AbstractNode) => ShikiTransformer;
 type CalloutOptions = Partial<{
     /**

package/dist/index.cjs

@@ -519,7 +519,9 @@ async function createHighlighter(documents, themes) {
 
 // src/lib/asciidoc/converters/sourceCodeConverter.ts
 var import_node_path2 = require("path");
-var sourceCodeConverter = ({ transformers, template }) => {
+var sourceCodeConverter = (converterOptions) => {
+  const transformers = converterOptions?.transformers;
+  const template = converterOptions?.template;
   return (options, highlighter) => {
     return {
       nodeContext: "listing",

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { LoaderContext } from 'astro/loaders';
-import { A as AsciidocLoader } from './index-sFlXF8Qm.cjs';
-export { a as AsciidocTemplate, C as CustomConverterFactoryFn, F as FilesystemTemplate, N as NodeContext, R as RawTemplate } from './index-sFlXF8Qm.cjs';
+import { A as AsciidocLoader } from './index-CS3PBqxf.cjs';
+export { a as AsciidocTemplate, C as CustomConverterFactoryFn, F as FilesystemTemplate, N as NodeContext, R as RawTemplate } from './index-CS3PBqxf.cjs';
 import 'shiki';
 import 'asciidoctor';
 import 'astro/zod';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { LoaderContext } from 'astro/loaders';
-import { A as AsciidocLoader } from './index-sFlXF8Qm.js';
-export { a as AsciidocTemplate, C as CustomConverterFactoryFn, F as FilesystemTemplate, N as NodeContext, R as RawTemplate } from './index-sFlXF8Qm.js';
+import { A as AsciidocLoader } from './index-CS3PBqxf.js';
+export { a as AsciidocTemplate, C as CustomConverterFactoryFn, F as FilesystemTemplate, N as NodeContext, R as RawTemplate } from './index-CS3PBqxf.js';
 import 'shiki';
 import 'asciidoctor';
 import 'astro/zod';

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   sourceCodeConverter
-} from "./chunk-KZRXEKZK.js";
+} from "./chunk-NC6IZHLR.js";
 import {
   transformAsciidocCallout
 } from "./chunk-5P6LDJGO.js";

package/dist/lib/asciidoc/converters/index.cjs

@@ -38,7 +38,9 @@ function splitFilenameComponents(filename) {
 }
 
 // src/lib/asciidoc/converters/sourceCodeConverter.ts
-var sourceCodeConverter = ({ transformers, template }) => {
+var sourceCodeConverter = (converterOptions) => {
+  const transformers = converterOptions?.transformers;
+  const template = converterOptions?.template;
   return (options, highlighter) => {
     return {
       nodeContext: "listing",

package/dist/lib/asciidoc/converters/index.d.cts

@@ -1,12 +1,12 @@
 import { ShikiTransformer } from 'shiki';
-import { C as CustomConverterFactoryFn, S as ShikiTransformerFactoryFn } from '../../../index-sFlXF8Qm.cjs';
+import { C as CustomConverterFactoryFn, S as ShikiTransformerFactoryFn } from '../../../index-CS3PBqxf.cjs';
 import 'asciidoctor';
 import 'astro/zod';
 
-type CodeBlockConverterOptions = {
+type CodeBlockConverterOptions = Partial<{
     transformers: Array<ShikiTransformer | ShikiTransformerFactoryFn>;
     template: string;
-};
-declare const sourceCodeConverter: CustomConverterFactoryFn<Partial<CodeBlockConverterOptions>>;
+}>;
+declare const sourceCodeConverter: CustomConverterFactoryFn<CodeBlockConverterOptions>;
 
 export { sourceCodeConverter };

package/dist/lib/asciidoc/converters/index.d.ts

@@ -1,12 +1,12 @@
 import { ShikiTransformer } from 'shiki';
-import { C as CustomConverterFactoryFn, S as ShikiTransformerFactoryFn } from '../../../index-sFlXF8Qm.js';
+import { C as CustomConverterFactoryFn, S as ShikiTransformerFactoryFn } from '../../../index-CS3PBqxf.js';
 import 'asciidoctor';
 import 'astro/zod';
 
-type CodeBlockConverterOptions = {
+type CodeBlockConverterOptions = Partial<{
     transformers: Array<ShikiTransformer | ShikiTransformerFactoryFn>;
     template: string;
-};
-declare const sourceCodeConverter: CustomConverterFactoryFn<Partial<CodeBlockConverterOptions>>;
+}>;
+declare const sourceCodeConverter: CustomConverterFactoryFn<CodeBlockConverterOptions>;
 
 export { sourceCodeConverter };

package/dist/lib/asciidoc/converters/index.js

@@ -1,6 +1,6 @@
 import {
   sourceCodeConverter
-} from "../../../chunk-KZRXEKZK.js";
+} from "../../../chunk-NC6IZHLR.js";
 import "../../../chunk-2UGTFP4R.js";
 export {
   sourceCodeConverter

package/dist/lib/asciidoc/templates/engines/index.d.cts

@@ -1,4 +1,4 @@
-import { c as AbstractEngine, a as AsciidocTemplate, T as TemplateModule, F as FilesystemTemplate, R as RawTemplate } from '../../../../index-sFlXF8Qm.cjs';
+import { c as AbstractEngine, a as AsciidocTemplate, T as TemplateModule, F as FilesystemTemplate, R as RawTemplate } from '../../../../index-CS3PBqxf.cjs';
 import { AbstractBlock } from 'asciidoctor';
 import 'shiki';
 import 'astro/zod';

package/dist/lib/asciidoc/templates/engines/index.d.ts

@@ -1,4 +1,4 @@
-import { c as AbstractEngine, a as AsciidocTemplate, T as TemplateModule, F as FilesystemTemplate, R as RawTemplate } from '../../../../index-sFlXF8Qm.js';
+import { c as AbstractEngine, a as AsciidocTemplate, T as TemplateModule, F as FilesystemTemplate, R as RawTemplate } from '../../../../index-CS3PBqxf.js';
 import { AbstractBlock } from 'asciidoctor';
 import 'shiki';
 import 'astro/zod';

package/dist/lib/shiki/transformers/index.cjs

@@ -21,7 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var transformers_exports = {};
 __export(transformers_exports, {
   transformAsciidocCallout: () => transformAsciidocCallout,
-  transformConsolePrompt: () => transformConsolePrompt
+  transformConsolePrompt: () => transformConsolePrompt,
+  transformerPrompt: () => transformerPrompt
 });
 module.exports = __toCommonJS(transformers_exports);
 
@@ -129,8 +130,39 @@ var transformConsolePrompt = (options) => {
     };
   };
 };
+
+// src/lib/shiki/transformers/transformerPrompt.ts
+var transformerPrompt = (options) => {
+  return (node) => {
+    const language = node.getAttribute("language");
+    const customPrompt = node.getAttribute(
+      options?.promptAttribute ?? "custom-prompt"
+    );
+    const promptToAdd = customPrompt ?? (options?.prompts && options.prompts[language]);
+    const cssClasses = typeof promptToAdd === "object" ? promptToAdd.cssClasses : options?.cssClasses;
+    return {
+      line(hast) {
+        if (!promptToAdd) return;
+        hast.children.unshift({
+          type: "element",
+          tagName: "span",
+          properties: {
+            class: cssClasses
+          },
+          children: [
+            {
+              type: "text",
+              value: typeof promptToAdd === "object" ? promptToAdd.prompt : promptToAdd
+            }
+          ]
+        });
+      }
+    };
+  };
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   transformAsciidocCallout,
-  transformConsolePrompt
+  transformConsolePrompt,
+  transformerPrompt
 });

package/dist/lib/shiki/transformers/index.d.cts

@@ -1,4 +1,5 @@
-import { b as ShikiTransformerFactory } from '../../../index-sFlXF8Qm.cjs';
+import { b as ShikiTransformerFactory } from '../../../index-CS3PBqxf.cjs';
+import { BundledLanguage } from 'shiki/types';
 import 'shiki';
 import 'asciidoctor';
 import 'astro/zod';
@@ -8,7 +9,7 @@ type TransformerOptions = Partial<{
 }>;
 declare const transformAsciidocCallout: ShikiTransformerFactory<TransformerOptions>;
 
-type TransformOptions = {
+type TransformOptions$1 = {
     /**
      * String of CSS classes to apply to leading prompt character(s) on
      * source code blocks of type console.
@@ -45,6 +46,34 @@ type TransformOptions = {
  *   before: <span>$</span><span> npm run dev</span>
  *   after:  <span>$</span><span>npm run dev</span>
  */
-declare const transformConsolePrompt: ShikiTransformerFactory<TransformOptions>;
+declare const transformConsolePrompt: ShikiTransformerFactory<TransformOptions$1>;
+
+type PromptOptions = {
+    prompt: string;
+    cssClasses: string;
+};
+type TransformOptions = {
+    /**
+     * String of CSS classes to apply to leading prompt character(s) on
+     * source code blocks of type console.
+     */
+    cssClasses?: string;
+    /**
+     * An object mapping each language block to a prompt string. An object
+     * can also be provided specified with two keys, the prompt and the
+     * css classes that modify this prompt in particular. Useful when you
+     * want to style them differently from the
+     * If not provided, it will default to look at the block attribute.
+     */
+    prompts?: Partial<Record<BundledLanguage, PromptOptions | string>>;
+    /**
+     * The name of the block attribute on the original document to look
+     * for and use as the prompt for this block.
+     *
+     * @default custom-prompt
+     */
+    promptAttribute?: string;
+};
+declare const transformerPrompt: ShikiTransformerFactory<TransformOptions>;
 
-export { transformAsciidocCallout, transformConsolePrompt };
+export { transformAsciidocCallout, transformConsolePrompt, transformerPrompt };

package/dist/lib/shiki/transformers/index.d.ts

@@ -1,4 +1,5 @@
-import { b as ShikiTransformerFactory } from '../../../index-sFlXF8Qm.js';
+import { b as ShikiTransformerFactory } from '../../../index-CS3PBqxf.js';
+import { BundledLanguage } from 'shiki/types';
 import 'shiki';
 import 'asciidoctor';
 import 'astro/zod';
@@ -8,7 +9,7 @@ type TransformerOptions = Partial<{
 }>;
 declare const transformAsciidocCallout: ShikiTransformerFactory<TransformerOptions>;
 
-type TransformOptions = {
+type TransformOptions$1 = {
     /**
      * String of CSS classes to apply to leading prompt character(s) on
      * source code blocks of type console.
@@ -45,6 +46,34 @@ type TransformOptions = {
  *   before: <span>$</span><span> npm run dev</span>
  *   after:  <span>$</span><span>npm run dev</span>
  */
-declare const transformConsolePrompt: ShikiTransformerFactory<TransformOptions>;
+declare const transformConsolePrompt: ShikiTransformerFactory<TransformOptions$1>;
+
+type PromptOptions = {
+    prompt: string;
+    cssClasses: string;
+};
+type TransformOptions = {
+    /**
+     * String of CSS classes to apply to leading prompt character(s) on
+     * source code blocks of type console.
+     */
+    cssClasses?: string;
+    /**
+     * An object mapping each language block to a prompt string. An object
+     * can also be provided specified with two keys, the prompt and the
+     * css classes that modify this prompt in particular. Useful when you
+     * want to style them differently from the
+     * If not provided, it will default to look at the block attribute.
+     */
+    prompts?: Partial<Record<BundledLanguage, PromptOptions | string>>;
+    /**
+     * The name of the block attribute on the original document to look
+     * for and use as the prompt for this block.
+     *
+     * @default custom-prompt
+     */
+    promptAttribute?: string;
+};
+declare const transformerPrompt: ShikiTransformerFactory<TransformOptions>;
 
-export { transformAsciidocCallout, transformConsolePrompt };
+export { transformAsciidocCallout, transformConsolePrompt, transformerPrompt };

package/dist/lib/shiki/transformers/index.js

@@ -43,7 +43,38 @@ var transformConsolePrompt = (options) => {
     };
   };
 };
+
+// src/lib/shiki/transformers/transformerPrompt.ts
+var transformerPrompt = (options) => {
+  return (node) => {
+    const language = node.getAttribute("language");
+    const customPrompt = node.getAttribute(
+      options?.promptAttribute ?? "custom-prompt"
+    );
+    const promptToAdd = customPrompt ?? (options?.prompts && options.prompts[language]);
+    const cssClasses = typeof promptToAdd === "object" ? promptToAdd.cssClasses : options?.cssClasses;
+    return {
+      line(hast) {
+        if (!promptToAdd) return;
+        hast.children.unshift({
+          type: "element",
+          tagName: "span",
+          properties: {
+            class: cssClasses
+          },
+          children: [
+            {
+              type: "text",
+              value: typeof promptToAdd === "object" ? promptToAdd.prompt : promptToAdd
+            }
+          ]
+        });
+      }
+    };
+  };
+};
 export {
   transformAsciidocCallout,
-  transformConsolePrompt
+  transformConsolePrompt,
+  transformerPrompt
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@d10f/asciidoc-astro-loader",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"description": "An Astro collections loader for Asciidoc files",
 	"author": "D10f",
 	"license": "MIT",