@d10f/asciidoc-astro-loader 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2025 D10f
+
+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,286 @@
+# Astro + Asciidoc combined
+
+This package will allow you to load Asciidoc files (with either an `.asciidoc` or `.adoc` extension) into an Astro Collection. It leverages [Asciidoctor.js](https://docs.asciidoctor.org/asciidoctor.js/latest) to do the heavy lifting, with a few but substantial configuration options added to make it more versatile.
+
+## Features
+
+- [x] Out of the box syntax highlighting, powered by [Shiki](https://shiki.style).
+- [x] Support for custom templating engines.
+- [x] Support for custom converters for maximum control over the output HTML.
+- [x] Full TypeScript support.
+
+## 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`:
+
+   ```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:
+
+    ```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(),
+        }),
+    });
+    ```
+
+
+## Configuration
+
+### Syntax Highlighting
+
+Syntax highlighting is already taken care of out of the box, but you can provide additional options to tweak things to your liking. For example, the default theme is Catppuccin, but you might want to use something else:
+
+```ts
+const blog = defineCollection({
+    loader: asciidocLoader({
+        base: ".src/content/blog",
+        syntaxHighlighting: {
+            theme: 'one-dark-pro',
+        }
+    }),
+});
+```
+
+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",
+			},
+		}
+	}),
+});
+```
+
+And even provide additional themes. Note that you will have to take care of implementing the logic to switch to that theme. Checkout [Shiki's documentation](https://shiki.style/guide/dual-themes#multiple-themes) to learn more.
+
+```ts
+const blog = defineCollection({
+	loader: asciidocLoader({
+		base: ".src/content/blog",
+		syntaxHighlighting: {
+			theme: {
+				light: "gruvbox-light-hard",
+				dark: "gruvbox-dark-hard",
+				dim: "gruvbox-dark-medium"
+			},
+		}
+	}),
+});
+```
+
+### Shiki Trasnformers
+
+One of the coolest features from Shiki are [transformers](https://shiki.style/guide/transformers). You can provide a list of the transformers that you want to use at the loader configuration:
+
+```ts
+import {
+	transformerNotationDiff,
+	transformerNotationFocus,
+	transformerNotationHighlight,
+} from '@shikijs/transformers';
+
+const blog = defineCollection({
+	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.
+
+## Custom Templates
+
+A nice feature of Asciidoctor.js is the use of default templates for rendering the different nodes, which can be overwritten by simply providing your own. With `asciidoc-astro-loader` you can easily provide a directory that contains your custom templates:
+
+```ts
+const blog = defineCollection({
+	loader: asciidocLoader({
+		base: ".src/content/blog",
+		document: {
+			template: "./usr/share/templates"
+		}
+	}),
+});
+```
+
+Just like regular Asciidoctor.js, any files located here will be used to replace content for nodes whose context matches the name of the template. That is, for a paragraph node, you would have a file named "paragraph.hbs", for example. This would use the Handlebars templating engine.
+
+### Registering A Templating Engine
+
+By default, only Handlebars and Nunjucks are available for processing templates, but you can create your own as well to leverage whatever other template engine you like. A template engine in the context of this package a class that extends the `AbstractEngine` class.
+
+```ts
+import { Php, Request } from '@platformatic/php-node';
+import { AbstractEngine } from '@d10f/asciidoc-astro-loader/engines';
+import type { AsciidocTemplate, FilesystemTemplate } from '@d10f/asciidoc-astro-loader';
+
+export class PhpEngine extends AbstractEngine implements AsciidocTemplate, FilesystemTemplate {
+    private server: Php;
+
+    constructor({ name = 'php', extensions = ['php'], root: string }) {
+        super(name, extensions);
+        this.server = new Php({ docroot: root });
+    }
+
+    /**
+     * This method is enforced by the AsciidocTemplate interface.
+     */
+    renderNode(node: AbstractBlock, options?: Record<string, unknown>) {}
+
+    /**
+     * This method is enforced by the FilesystemTemplate interface.
+     */
+	renderFile(filepath: string, options?: Record<string, unknown>) {}
+}
+```
+
+Implementing these template interfaces is completely optional, but they help keeping things organized, predictable, easy to test, etc. The `AsciidocTemplate` interface is particularly important, however, as it enforces the implementation of the `renderNode` method, which will be invoked automatically whenever a template file exists with a file extension supported by this engine.
+
+> [!WARNING]
+> (WIP): The render methods must not return a Promise.
+
+When your engine is ready, you can import it and pass it to the loader configuration object:
+
+```ts
+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' })
+			],
+		}
+	}),
+});
+```
+
+For completeness, this is what a basic implementation of the above example might look like:
+
+```ts
+import { Php, Request } from '@platformatic/php-node';
+import { AbstractEngine } from '@d10f/asciidoc-astro-loader/engines';
+
+import type { AbstractBlock } from 'asciidoctor';
+import type {
+	AsciidocTemplate,
+	FilesystemTemplate,
+	NodeContext
+} from '@d10f/asciidoc-astro-loader';
+
+export class PhpEngine extends AbstractEngine implements AsciidocTemplate, FilesystemTemplate {
+	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();
+	}
+}
+```
+
+We can now have a template file such as "paragraph.php" that will be processed by this engine. Leveraging Platformatic's module, we can write template files in native PHP via WebAssembly!
+
+```php
+<?php
+$body = json_decode(file_get_contents('php://input'));
+?>
+
+<p><?= strtoupper($body->content) ?></p>
+```
+
+## Custom Converters
+
+Custom converters are refined versions of templates. The main difference is that they can be configured further, which gives more granular control over the conversion of Asciidoc blocks. An example of custom converters in action comes from the syntax highlighting that's built into `asciidoc-astro-loader`, which processes the node through Shiki.
+
+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.
+
+### 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.
+
+```ts
+import type { CustomConverterFactoryFn, NodeContext } from '@d10f/asciidoc-astro-loader';
+
+export const customConverter: CustomConverterFactoryFn = ({ nodeContext }) => {
+    return (options, highlighter) => {
+        return {
+
+            /**
+             * The type of node that this converter will act upon. It
+             * can either be hard-coded here, or passed as an option.
+             */
+            nodeContext,
+
+            /**
+             * The convert function that will produce the HTML output.
+             * It receives the node that it will convert, and an
+             * instance of the template engine registry, which you can
+             * use to access any and all available templat engines to
+             * customize the output even further.
+             */
+            convert(node, templateEngine) {
+                return '<p>Result!</p>';
+            }
+        };
+    }
+}
+```
+

package/dist/chunk-2F52PMNV.js

@@ -0,0 +1,132 @@
+// src/lib/asciidoc/templates/engines/Base.ts
+var AbstractEngine = class {
+  constructor(_name, _extensions) {
+    this._name = _name;
+    this._extensions = _extensions;
+    this.templateList = /* @__PURE__ */ new Map();
+  }
+  templateList;
+  /**
+   * Returns the given name to this template engine.
+   */
+  get name() {
+    return this._name;
+  }
+  /**
+   * Returns the list of extensions this template engine supports.
+   */
+  get extensions() {
+    return this._extensions;
+  }
+  /**
+   * Accessor method to check if instance implements the
+   * TemplateModule interface.
+   */
+  get canLoad() {
+    return "load" in this && typeof this.load === "function";
+  }
+  /**
+   * Accessor method to check if instance implements the
+   * AsciidocTemplate interface.
+   */
+  get canRenderNode() {
+    return "renderNode" in this && typeof this.renderNode === "function";
+  }
+  /**
+   * Accessor method to check if instance implements the
+   * FilesystemTemplate interface.
+   */
+  get canRenderFile() {
+    return "renderFile" in this && typeof this.renderFile === "function";
+  }
+  /**
+   * Accessor method to check if instance implements the
+   * RawTemplate interface.
+   */
+  get canRenderString() {
+    return "renderString" in this && typeof this.renderString === "function";
+  }
+  /**
+   * Appends a new context that this template engine will act upon.
+   */
+  addContext(context, filepath) {
+    this.templateList.set(context, filepath);
+  }
+  /**
+   * Verifies whether the specified context is being tracked or not.
+   */
+  hasContext(context) {
+    return typeof context === "string" ? this.templateList.has(context) : this.templateList.has(context.getNodeName());
+  }
+  /**
+   * Verifies if the specified file extension is supported
+   * by this template engine.
+   */
+  supportsExt(extension) {
+    return this.extensions.includes(extension);
+  }
+};
+
+// src/lib/asciidoc/templates/engines/Handlebars.ts
+import { readFileSync } from "fs";
+var HandlebarsEngine = class extends AbstractEngine {
+  render;
+  constructor(name = "handlebars", extensions = ["handlebars", "hbs"]) {
+    super(name, extensions);
+    this.render = null;
+  }
+  async load() {
+    const Handlebars = await import("handlebars");
+    this.render = (input, opts) => {
+      return Handlebars.default.compile(input)(opts);
+    };
+  }
+  renderNode(node, options = {}) {
+    const context = node.getNodeName();
+    return this.renderFile(this.templateList.get(context), options);
+  }
+  renderFile(filepath, options = {}) {
+    const fileContents = readFileSync(filepath, { encoding: "utf8" });
+    return this.renderString(fileContents, options);
+  }
+  renderString(str, options = {}) {
+    if (this.render === null) {
+      throw new Error("This template doesn't have a render method!");
+    }
+    return this.render(str, options);
+  }
+};
+
+// src/lib/asciidoc/templates/engines/Nunjucks.ts
+import { readFileSync as readFileSync2 } from "fs";
+var NunjucksEngine = class extends AbstractEngine {
+  render;
+  constructor(name = "nunjucks", extensions = ["nunjucks", "njk"]) {
+    super(name, extensions);
+    this.render = null;
+  }
+  async load() {
+    const nunjucks = await import("nunjucks");
+    this.render = nunjucks.default.renderString;
+  }
+  renderNode(node, options = {}) {
+    const context = node.getNodeName();
+    return this.renderFile(this.templateList.get(context), options);
+  }
+  renderFile(filepath, options = {}) {
+    const fileContents = readFileSync2(filepath, { encoding: "utf8" });
+    return this.renderString(fileContents, options);
+  }
+  renderString(str, options = {}) {
+    if (this.render === null) {
+      throw new Error("This template doesn't have a render method!");
+    }
+    return this.render(str, options);
+  }
+};
+
+export {
+  AbstractEngine,
+  HandlebarsEngine,
+  NunjucksEngine
+};

package/dist/chunk-DDIUST2Z.js

@@ -0,0 +1,113 @@
+// 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
+  };
+}
+
+// src/lib/shiki/transformers/transformAsciidocCallout.ts
+function transformAsciidocCallout({
+  node,
+  cssClasses = "pointer-events-none select-none ml-2"
+}) {
+  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(`(?:${lineComments.join("|")})((?:\\s+<(\\d+)>)+)`),
+    // Handles XML comments
+    new RegExp(/((?:\s*<!--(\d+)-->)+)/)
+  ];
+  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].trim().replaceAll(/(?:<!--|-->|[<>])/g, "").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: "i",
+          properties: {
+            class: `conum ${cssClasses}`,
+            "data-value": calloutId
+          },
+          children: [
+            {
+              type: "element",
+              tagName: "b",
+              properties: {},
+              children: [
+                {
+                  type: "text",
+                  value: calloutId
+                }
+              ]
+            }
+          ]
+        });
+      });
+    }
+  };
+}
+
+// src/lib/shiki/transformers/transformConsoleCodeBlock.ts
+function transformConsoleCodeBlock(options = {
+  cssClasses: "pointer-events-none select-none mr-2 opacity-50"
+}) {
+  const unselectablePrompt = `<span $1 class="${options.cssClasses}">$</span>`;
+  const linePrefix = '<span class="line[^>]+?>';
+  const splitPrompt = new RegExp(
+    `(?<=${linePrefix})(?:<span (style="[^"]*?")>\\s*?\\$\\s+?([^<]))`
+  );
+  const trimWhitespace = new RegExp(
+    `(?<=${linePrefix})(?:<span (style="[^"]*?")>\\s*?\\$\\s*?<\\/span>(?:<span>\\s+<\\/span>)?)`
+  );
+  const trimWhitespaceAhead = new RegExp(
+    `(?<=${linePrefix}<span [^>]+?>\\$<\\/span>)(<span style="[^"]+?">)\\s+?`
+  );
+  return {
+    postprocess: (html, { lang }) => {
+      if (lang === "console") {
+        return html.split("\n").map((line) => {
+          return line.replace(
+            splitPrompt,
+            unselectablePrompt + "<span $1>$2"
+          ).replace(trimWhitespace, unselectablePrompt).replace(trimWhitespaceAhead, "$1");
+        }).join("\n");
+      }
+    }
+  };
+}
+
+export {
+  slugify,
+  splitFilenameComponents,
+  transformAsciidocCallout,
+  transformConsoleCodeBlock
+};

package/dist/chunk-HAZIHU2Y.js

@@ -0,0 +1,56 @@
+import {
+  splitFilenameComponents,
+  transformAsciidocCallout,
+  transformConsoleCodeBlock
+} from "./chunk-DDIUST2Z.js";
+
+// src/lib/asciidoc/converters/sourceCodeConverter.ts
+import {
+  transformerNotationDiff,
+  transformerNotationFocus,
+  transformerNotationHighlight
+} from "@shikijs/transformers";
+import { resolve } from "path";
+var sourceCodeConverter = ({ nodeContext, transformers, template }) => {
+  return (options, highlighter) => {
+    return {
+      nodeContext: nodeContext ?? "listing",
+      convert(node, templateEngine) {
+        const input = node.getSourceLines().join("\n");
+        const lang = node.getAttribute("language");
+        const output = highlighter.codeToHtml(input, {
+          ...options.syntaxHighlighting,
+          lang,
+          transformers: [
+            ...transformers ?? [],
+            transformerNotationDiff(),
+            transformerNotationHighlight(),
+            transformerNotationFocus(),
+            transformAsciidocCallout({ node }),
+            transformConsoleCodeBlock()
+          ]
+        });
+        if (templateEngine && template) {
+          const { extension } = splitFilenameComponents(template);
+          const engine = templateEngine.getEngineByExtension(
+            extension || ""
+          );
+          if (engine) {
+            const templateFile = resolve(process.cwd(), template);
+            if (engine.canRenderFile) {
+              return engine.renderFile(templateFile, {
+                content: output,
+                lang
+              });
+            }
+          }
+        }
+        return output;
+      }
+    };
+  };
+};
+
+export {
+  sourceCodeConverter
+};