@d10f/asciidoc-astro-loader 0.1.0 → 0.2.1

package/README.md

@@ -353,18 +353,27 @@ Using a converter might make more sense if you need to keep some state as the do
 
 ## Example
 
-This is an example taken from my own website to showcase how to use it in a real world setting. This configuration uses a custom converter, a custom Shiki transformer and points to a folder where custom templates are found:
+This is an example taken from my own website to showcase how to use it in a real world setting:
 
 ```ts
 const blog = defineCollection({
 	loader: asciidocLoader({
 		base: 'src/content/blog',
+		images: {
+			imageUrl: '/',
+		},
 		document: {
 			template: './src/templates',
-			converters: [admonitionConverter()],
+			converters: [
+				admonitionConverter(),
+				xrefConverter()
+			],
 		},
 		syntaxHighlighting: {
-			theme: 'catppuccin-frappe',
+			theme: {
+				light: 'catppuccin-latte',
+				dark: 'catppuccin-frappe',
+			},
 			transformers: [
 				transformerNotationDiff(),
 				transformerNotationErrorLevel(),
@@ -373,6 +382,9 @@ const blog = defineCollection({
 				transformerPrompt({
 					langs: {
 						console: '$',
+						prolog: {
+							hideBreak: true,
+						},
 					},
 					cssClasses: 'unselectable mr-2 opacity-50',
 				}),
@@ -382,10 +394,38 @@ const blog = defineCollection({
 			},
 		},
 	}),
-	schema: z.object({
-		doctitle: z.string(),
-		description: z.string(),
-		revdate: z.coerce.date(),
-	}),
+	schema: z
+		.object({
+			doctitle: z.string(),
+			description: z.string(),
+			revdate: z.coerce.date(),
+			keywords: z.string().transform((t) => t.split(', ')),
+			technologies: z.string().transform((t) => t.split(' ')),
+			series: z.string().optional(),
+			'series-prev': z.string().optional(),
+			'series-next': z.string().optional(),
+			'series-description': z.string().optional(),
+		})
+		.transform(({ doctitle, revdate, ...rest }) => ({
+			title: doctitle,
+			createdAt: revdate,
+			...rest,
+		})),
 });
 ```
+
+This configuration uses a couple of custom converters, a custom Shiki transformer and points to a folder where custom templates are found.
+
+The first converter applies a simple CSS rule so that admonitions are placed on either side of the main document, in an alternate fashion.
+
+The other converter is a little helper to rectify cross-reference links to other documents. I created it because cross-reference in AsciiDoc works by referencing a filename, whereas Astro uses the post title as the URL slug, which makes more sense in the context of the web. This converter handles the conversion so that I can keep things organized neatly based on what makes more sense: use filenames in the file system, and URL slugs in the web.
+
+As for the custom Shiki transformer, that's just so that I control how code snippets look like when there's either a prefix expected, or when multi-line is supported. The classic example of this are console commands, but REPL interpreters are also a good example.
+
+Here you can see it in action with a command that is written over multiple lines for clarity (horizontal overflow not shown here):
+
+![A ffmpeg command written over multiple lines showing only a single prompt](./assets/code-snippet-transformer-console.avif)
+
+Notice the escaping of the newline character, which you might want to omit with the `hideBreak` option. This is useful to distinguish code from REPL interpreters:
+
+![A Prolog interpreter running a command that spans over multiple lines](./assets/code-snippet-transformer-prolog.avif)

package/dist/{chunk-TCLZUBH3.js → chunk-KPBQHX55.js}

@@ -5,7 +5,7 @@ import {
 // src/lib/shiki/transformers/transformAsciidocCallout.ts
 var transformAsciidocCallout = (options) => {
   return (node) => {
-    const lineComments = ["//", "#", ";;", "%"];
+    const lineComments = ["//", "#", ";;", "%", "--"];
     const customLineComment = node.getAttribute("line-comment");
     if (customLineComment) {
       lineComments.push(escapeRegexCharacters(customLineComment));

package/dist/{index-B1d5alka.d.cts → index-Bbw2Lfb5.d.cts}

@@ -1,5 +1,5 @@
-import { HighlighterCore, CodeToHastOptions, CodeOptionsMultipleThemes, StringLiteralUnion, BundledTheme, ShikiTransformer } from 'shiki';
-import { AbstractNode, AbstractBlock } from 'asciidoctor';
+import { BundledLanguage, HighlighterCore, CodeToHastOptions, CodeOptionsMultipleThemes, StringLiteralUnion, BundledTheme, ShikiTransformer } from 'shiki';
+import { AbstractNode, AbstractBlock, Document } from 'asciidoctor';
 import { z } from 'astro/zod';
 
 type RequiredOptions = z.output<typeof loaderOptionsSchema>;
@@ -169,6 +169,27 @@ declare class TemplateEngineRegistry {
     private loadTemplates;
 }
 
+declare class AsciidocDocument {
+    private document;
+    private baseConverter;
+    constructor(filepath: string);
+    private get documentTitle();
+    get attributes(): any;
+    get title(): string;
+    get subtitle(): string;
+    get slug(): string;
+    get preamble(): string | undefined;
+    get description(): string;
+    get author(): string;
+    get authors(): Document.Author[];
+    get version(): string;
+    get createdAt(): string;
+    get keywords(): any;
+    get languages(): Set<BundledLanguage>;
+    setAttribute(attribute: string, value: string): void;
+    convert(converters?: CustomConverter[], templateEngine?: TemplateEngineRegistry): string;
+}
+
 /**
  * Checks if the given property K is required in object T.
  *
@@ -206,7 +227,7 @@ type CustomConverter = {
     convert(node: AbstractNode, templateEngine?: TemplateEngineRegistry): string | null | undefined;
 };
 type CustomConverterFactoryFn<T extends object> = HasRequiredKeys<T> extends true ? (converterOptions: T) => CustomConverterFn : (converterOptions?: T) => CustomConverterFn;
-type CustomConverterFn = (opts: RequiredOptions, highlighter: HighlighterCore) => CustomConverter;
+type CustomConverterFn = (opts: RequiredOptions, highlighter: HighlighterCore, docs: AsciidocDocument[]) => CustomConverter;
 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-B1d5alka.d.ts → index-Bbw2Lfb5.d.ts}

@@ -1,5 +1,5 @@
-import { HighlighterCore, CodeToHastOptions, CodeOptionsMultipleThemes, StringLiteralUnion, BundledTheme, ShikiTransformer } from 'shiki';
-import { AbstractNode, AbstractBlock } from 'asciidoctor';
+import { BundledLanguage, HighlighterCore, CodeToHastOptions, CodeOptionsMultipleThemes, StringLiteralUnion, BundledTheme, ShikiTransformer } from 'shiki';
+import { AbstractNode, AbstractBlock, Document } from 'asciidoctor';
 import { z } from 'astro/zod';
 
 type RequiredOptions = z.output<typeof loaderOptionsSchema>;
@@ -169,6 +169,27 @@ declare class TemplateEngineRegistry {
     private loadTemplates;
 }
 
+declare class AsciidocDocument {
+    private document;
+    private baseConverter;
+    constructor(filepath: string);
+    private get documentTitle();
+    get attributes(): any;
+    get title(): string;
+    get subtitle(): string;
+    get slug(): string;
+    get preamble(): string | undefined;
+    get description(): string;
+    get author(): string;
+    get authors(): Document.Author[];
+    get version(): string;
+    get createdAt(): string;
+    get keywords(): any;
+    get languages(): Set<BundledLanguage>;
+    setAttribute(attribute: string, value: string): void;
+    convert(converters?: CustomConverter[], templateEngine?: TemplateEngineRegistry): string;
+}
+
 /**
  * Checks if the given property K is required in object T.
  *
@@ -206,7 +227,7 @@ type CustomConverter = {
     convert(node: AbstractNode, templateEngine?: TemplateEngineRegistry): string | null | undefined;
 };
 type CustomConverterFactoryFn<T extends object> = HasRequiredKeys<T> extends true ? (converterOptions: T) => CustomConverterFn : (converterOptions?: T) => CustomConverterFn;
-type CustomConverterFn = (opts: RequiredOptions, highlighter: HighlighterCore) => CustomConverter;
+type CustomConverterFn = (opts: RequiredOptions, highlighter: HighlighterCore, docs: AsciidocDocument[]) => CustomConverter;
 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

@@ -617,7 +617,7 @@ var sourceCodeConverter = (converterOptions) => {
 // src/lib/shiki/transformers/transformAsciidocCallout.ts
 var transformAsciidocCallout = (options) => {
   return (node) => {
-    const lineComments = ["//", "#", ";;", "%"];
+    const lineComments = ["//", "#", ";;", "%", "--"];
     const customLineComment = node.getAttribute("line-comment");
     if (customLineComment) {
       lineComments.push(escapeRegexCharacters(customLineComment));
@@ -721,7 +721,7 @@ function asciidocLoader(_options) {
         );
       }
       const converters = options.document.converters.map(
-        (converter) => converter(options, highlighter)
+        (converter) => converter(options, highlighter, docs)
       );
       const hasSourceCodeConverter = converters.find(
         (converter) => converter.nodeContext === "listing" && converter?.nodeStyle === "source"
@@ -735,7 +735,7 @@ function asciidocLoader(_options) {
                 options.syntaxHighlighting.callouts
               )
             ]
-          })(options, highlighter)
+          })(options, highlighter, docs)
         );
       }
       await Promise.all(

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { LoaderContext } from 'astro/loaders';
-import { a as AsciidocLoader } from './index-B1d5alka.cjs';
-export { b as AsciidocTemplate, C as CustomConverterFactoryFn, F as FilesystemTemplate, N as NodeContext, R as RawTemplate } from './index-B1d5alka.cjs';
+import { a as AsciidocLoader } from './index-Bbw2Lfb5.cjs';
+export { b as AsciidocTemplate, C as CustomConverterFactoryFn, F as FilesystemTemplate, N as NodeContext, R as RawTemplate } from './index-Bbw2Lfb5.cjs';
 export { transformAsciidocCallout, transformerPrompt } from './lib/shiki/transformers/index.cjs';
 import 'shiki';
 import 'asciidoctor';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { LoaderContext } from 'astro/loaders';
-import { a as AsciidocLoader } from './index-B1d5alka.js';
-export { b as AsciidocTemplate, C as CustomConverterFactoryFn, F as FilesystemTemplate, N as NodeContext, R as RawTemplate } from './index-B1d5alka.js';
+import { a as AsciidocLoader } from './index-Bbw2Lfb5.js';
+export { b as AsciidocTemplate, C as CustomConverterFactoryFn, F as FilesystemTemplate, N as NodeContext, R as RawTemplate } from './index-Bbw2Lfb5.js';
 export { transformAsciidocCallout, transformerPrompt } from './lib/shiki/transformers/index.js';
 import 'shiki';
 import 'asciidoctor';

package/dist/index.js

@@ -1,10 +1,10 @@
-import {
-  sourceCodeConverter
-} from "./chunk-SUQERYPQ.js";
 import {
   transformAsciidocCallout,
   transformerPrompt
-} from "./chunk-TCLZUBH3.js";
+} from "./chunk-KPBQHX55.js";
+import {
+  sourceCodeConverter
+} from "./chunk-SUQERYPQ.js";
 import {
   slugify,
   splitFilenameComponents
@@ -429,7 +429,7 @@ function asciidocLoader(_options) {
         );
       }
       const converters = options.document.converters.map(
-        (converter) => converter(options, highlighter)
+        (converter) => converter(options, highlighter, docs)
       );
       const hasSourceCodeConverter = converters.find(
         (converter) => converter.nodeContext === "listing" && converter?.nodeStyle === "source"
@@ -443,7 +443,7 @@ function asciidocLoader(_options) {
                 options.syntaxHighlighting.callouts
               )
             ]
-          })(options, highlighter)
+          })(options, highlighter, docs)
         );
       }
       await Promise.all(

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

@@ -1,5 +1,5 @@
 import { ShikiTransformer } from 'shiki';
-import { C as CustomConverterFactoryFn, c as ShikiTransformerFactoryFn } from '../../../index-B1d5alka.cjs';
+import { C as CustomConverterFactoryFn, c as ShikiTransformerFactoryFn } from '../../../index-Bbw2Lfb5.cjs';
 import 'asciidoctor';
 import 'astro/zod';
 

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

@@ -1,5 +1,5 @@
 import { ShikiTransformer } from 'shiki';
-import { C as CustomConverterFactoryFn, c as ShikiTransformerFactoryFn } from '../../../index-B1d5alka.js';
+import { C as CustomConverterFactoryFn, c as ShikiTransformerFactoryFn } from '../../../index-Bbw2Lfb5.js';
 import 'asciidoctor';
 import 'astro/zod';
 

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

@@ -1,4 +1,4 @@
-import { A as AbstractEngine, b as AsciidocTemplate, T as TemplateModule, F as FilesystemTemplate, R as RawTemplate } from '../../../../index-B1d5alka.cjs';
+import { A as AbstractEngine, b as AsciidocTemplate, T as TemplateModule, F as FilesystemTemplate, R as RawTemplate } from '../../../../index-Bbw2Lfb5.cjs';
 import { AbstractBlock } from 'asciidoctor';
 import 'shiki';
 import 'astro/zod';

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

@@ -1,4 +1,4 @@
-import { A as AbstractEngine, b as AsciidocTemplate, T as TemplateModule, F as FilesystemTemplate, R as RawTemplate } from '../../../../index-B1d5alka.js';
+import { A as AbstractEngine, b as AsciidocTemplate, T as TemplateModule, F as FilesystemTemplate, R as RawTemplate } from '../../../../index-Bbw2Lfb5.js';
 import { AbstractBlock } from 'asciidoctor';
 import 'shiki';
 import 'astro/zod';

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

@@ -34,7 +34,7 @@ function escapeRegexCharacters(str) {
 // src/lib/shiki/transformers/transformAsciidocCallout.ts
 var transformAsciidocCallout = (options) => {
   return (node) => {
-    const lineComments = ["//", "#", ";;", "%"];
+    const lineComments = ["//", "#", ";;", "%", "--"];
     const customLineComment = node.getAttribute("line-comment");
     if (customLineComment) {
       lineComments.push(escapeRegexCharacters(customLineComment));

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

@@ -1,4 +1,4 @@
-import { S as ShikiTransformerFactory } from '../../../index-B1d5alka.cjs';
+import { S as ShikiTransformerFactory } from '../../../index-Bbw2Lfb5.cjs';
 import { BundledLanguage } from 'shiki';
 import 'asciidoctor';
 import 'astro/zod';

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

@@ -1,4 +1,4 @@
-import { S as ShikiTransformerFactory } from '../../../index-B1d5alka.js';
+import { S as ShikiTransformerFactory } from '../../../index-Bbw2Lfb5.js';
 import { BundledLanguage } from 'shiki';
 import 'asciidoctor';
 import 'astro/zod';

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

@@ -1,7 +1,7 @@
 import {
   transformAsciidocCallout,
   transformerPrompt
-} from "../../../chunk-TCLZUBH3.js";
+} from "../../../chunk-KPBQHX55.js";
 import "../../../chunk-2UGTFP4R.js";
 export {
   transformAsciidocCallout,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@d10f/asciidoc-astro-loader",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "An Astro collections loader for Asciidoc files",
 	"author": "D10f",
 	"license": "MIT",
@@ -47,12 +47,12 @@
 		"tsup": "^8.5.0",
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.45.0",
-		"vitest": "^3.2.4"
+		"vitest": "^5.0.3"
 	},
 	"dependencies": {
-		"@shikijs/transformers": "^3.20.0",
+		"@shikijs/transformers": "^4.5.0",
 		"asciidoctor": "^3.0.4",
-		"shiki": "^3.20.0"
+		"shiki": "^4.5.0"
 	},
 	"peerDependencies": {
 		"astro": "^6.3.1"