docusaurus-plugin-docusynx 0.1.2 → 0.1.4

package/README.md

@@ -59,6 +59,10 @@ export default defineComponentHandler({
 The handler key is the exact `importSource` and `exportName`. An unknown imported
 MDX component stops the build. The plugin does not execute an unknown component.
 
+Mermaid rendering is included. Excalidraw rendering requires the optional
+`@excalidraw/utils@0.1.5` peer dependency. Install it only when the documentation
+contains an Excalidraw diagram that Docusynx must render.
+
 `sourcePathPrefix` changes site-relative paths into repository-relative paths.
 The `source_path` or `docusynx_source_path` frontmatter field overrides the path
 with an already repository-relative value. The prefix is not applied to an

package/dist/assets.d.ts

@@ -3,5 +3,6 @@ export declare class AssetCollector {
     #private;
     constructor(outputDirectory: string);
     add(sourcePath: string, mimeType?: string): Promise<string>;
+    addBytes(content: string | Uint8Array, extension: string, mimeType?: string): Promise<string>;
     values(): BundleAsset[];
 }

package/dist/assets.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
-import { copyFile, mkdir, readFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { assertSafeSvg } from './svg.js';
 const MIME_BY_EXTENSION = {
     '.gif': 'image/gif',
     '.jpeg': 'image/jpeg',
@@ -17,21 +18,47 @@ export class AssetCollector {
     }
     async add(sourcePath, mimeType) {
         const bytes = await readFile(sourcePath);
+        return this.addBytes(bytes, path.extname(sourcePath).toLowerCase(), mimeType);
+    }
+    async addBytes(content, extension, mimeType) {
+        if (!/^\.[a-z0-9]+$/.test(extension)) {
+            throw new Error(`invalid asset extension ${JSON.stringify(extension)}`);
+        }
+        const bytes = typeof content === 'string' ? Buffer.from(content, 'utf8') : content;
         const digest = createHash('sha256').update(bytes).digest('hex');
-        const extension = path.extname(sourcePath).toLowerCase();
         const id = `sha256:${digest}`;
         const relativePath = `assets/${digest}${extension}`;
-        if (!this.#assets.has(id)) {
+        const resolvedMimeType = mimeType ??
+            MIME_BY_EXTENSION[extension] ??
+            'application/octet-stream';
+        if (extension === '.svg' ||
+            resolvedMimeType.split(';', 1)[0]?.trim().toLowerCase() ===
+                'image/svg+xml') {
+            let svg;
+            try {
+                svg = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch {
+                throw new Error('unsafe SVG content: invalid UTF-8');
+            }
+            assertSafeSvg(svg);
+        }
+        const existing = this.#assets.get(id);
+        if (existing) {
+            if (existing.path !== relativePath ||
+                existing.mimeType !== resolvedMimeType) {
+                throw new Error(`asset metadata conflicts for ${id}`);
+            }
+        }
+        else {
             await mkdir(path.join(this.#outputDirectory, 'assets'), {
                 recursive: true,
             });
-            await copyFile(sourcePath, path.join(this.#outputDirectory, relativePath));
+            await writeFile(path.join(this.#outputDirectory, relativePath), bytes);
             this.#assets.set(id, {
                 id,
                 path: relativePath,
-                mimeType: mimeType ??
-                    MIME_BY_EXTENSION[extension] ??
-                    'application/octet-stream',
+                mimeType: resolvedMimeType,
                 hash: id,
             });
         }

package/dist/markdown.js

@@ -184,7 +184,9 @@ async function transformComponent(node, context) {
         siteDir: context.siteDir,
         sourcePath: context.sourcePath,
         readSiteFile: async (requestedPath) => readFile(resolveSitePath(context.siteDir, requestedPath), 'utf8'),
-        addAsset: async (input) => context.assets.add(resolveSitePath(context.siteDir, input.path), input.mimeType),
+        addAsset: async (input) => 'path' in input
+            ? context.assets.add(resolveSitePath(context.siteDir, input.path), input.mimeType)
+            : context.assets.addBytes(input.content, input.extension, input.mimeType),
         transformChildren: async () => transformBlockChildren(children, context),
     };
     const result = await handler.transform(handlerContext);

package/dist/types.d.ts

@@ -98,10 +98,14 @@ export interface DocumentBundle {
     assets: BundleAsset[];
     hash: string;
 }
-export interface ComponentHandlerAssetInput {
+export type ComponentHandlerAssetInput = {
     path: string;
     mimeType?: string;
-}
+} | {
+    content: string | Uint8Array;
+    extension: '.svg';
+    mimeType: 'image/svg+xml';
+};
 export interface ComponentHandlerContext {
     readonly node: MdxAstNode;
     readonly props: Readonly<Record<string, unknown>>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "docusaurus-plugin-docusynx",
-    "version": "0.1.2",
+    "version": "0.1.4",
     "description": "Export a deterministic Docusaurus document bundle for docusynx",
     "license": "Apache-2.0",
     "repository": {
@@ -38,11 +38,15 @@
         "node": ">=22.13"
     },
     "peerDependencies": {
-        "@docusaurus/core": "^3.10.0"
+        "@docusaurus/core": "^3.10.0",
+        "@excalidraw/utils": "0.1.5"
     },
     "peerDependenciesMeta": {
         "@docusaurus/core": {
             "optional": true
+        },
+        "@excalidraw/utils": {
+            "optional": true
         }
     },
     "publishConfig": {
@@ -50,7 +54,6 @@
         "registry": "https://registry.npmjs.org/"
     },
     "dependencies": {
-        "@excalidraw/utils": "0.1.5",
         "cheerio": "1.0.0",
         "css-tree": "2.3.1",
         "domhandler": "5.0.3",
@@ -68,6 +71,7 @@
         "unified": "11.0.5"
     },
     "devDependencies": {
+        "@excalidraw/utils": "0.1.5",
         "@types/jsdom": "21.1.7",
         "@types/node": "22.15.3",
         "@types/svgdom": "0.1.2",