add option for root file

Author: essential-randomness

remark-alt-text-files/README.md

@@ -0,0 +1,37 @@
+# @fujocoded/remark-alt-text-files
+
+A remark plugin that allows loading alt text from a file, rather than hardocding it in markdown
+
+## Sample usage
+
+In `astro.config.js`:
+
+```ts
+import remarkAltTextFiles from "@fujocoded/remark-alt-text-files";
+
+export default defineConfig({
+  // ...
+  integrations: [
+    mdx({
+      remarkPlugins: [remarkAltTextFiles],
+    }),
+  ],
+});
+```
+
+In markdown files:
+
+```md
+![regular alt text](./image.png)
+
+![file:path/to/alt/text.alt.txt](./image.png)
+
+# This will load alt text from "./image.alt.txt"
+
+![file:](./image.png)
+```
+
+You can change the following options:
+
+- `root`: where the alt text file will be searched from (default: the loaded path of the markdown file or `process.cwd()`)
+- `pathPrefix`: the prefix to indicate alt text should be loaded from a file (default: `file:`)

remark-alt-text-files/index.ts

@@ -6,35 +6,41 @@ import { VFile } from "vfile";
 
 import type mdast from "mdast";
 
-interface PluginArgs {
+export interface PluginArgs {
   pathPrefix?: string;
+  root?: string;
 }
 
 const getFilePath = ({
   imageNode,
   vfile,
-  pathPrefix,
+  options,
 }: {
   imageNode: mdast.Image;
   vfile: VFile;
-  pathPrefix: string;
+  options: PluginArgs & { pathPrefix: string };
 }) => {
-  let filePath = imageNode.alt!.replace(pathPrefix, "");
+  let filePath = imageNode.alt!.replace(options.pathPrefix, "");
   if (filePath == "") {
     // We use the name of the imageNode file and replace the extension with .alt.txt
     filePath = imageNode.url.replace(/\.[^.]+$/, ".alt.txt")!;
   }
 
   return join(
-    // If this was loaded from a file, then use the directory of that file
+    // If the root is provided, use it
+    // Otherwise, if this was loaded from a file, then use the directory of that file
     // Otherwise, use the current working directory
-    vfile.history[0] ? dirname(vfile.history[0]) : process.cwd(),
+    options.root
+      ? options.root
+      : vfile.history[0]
+      ? dirname(vfile.history[0])
+      : process.cwd(),
     filePath
   );
 };
 
 const plugin: Plugin<PluginArgs[], mdast.Root> =
-  ({ pathPrefix = "file:" } = {}) =>
+  ({ pathPrefix = "file:", root } = {}) =>
   async (tree, vfile) => {
     const loadingAltText: Promise<string>[] = [];
     const loadingAltFiles: string[] = [];
@@ -43,7 +49,11 @@ const plugin: Plugin<PluginArgs[], mdast.Root> =
       if (!node.alt || !node.alt.startsWith(pathPrefix)) {
         return;
       }
-      const filePath = getFilePath({ imageNode: node, vfile, pathPrefix });
+      const filePath = getFilePath({
+        imageNode: node,
+        vfile,
+        options: { pathPrefix, root },
+      });
       loadingAltText.push(
         readFile(filePath, "utf8").then((text) => (node.alt = text.trim()))
       );

remark-alt-text-files/tests/index.test.ts

@@ -3,7 +3,7 @@ import { remark } from "remark";
 import { Compatible, VFile } from "vfile";
 import { fs, vol } from "memfs";
 import { pathToFileURL } from "node:url";
-import remarkAltTextFiles from "../index.ts";
+import remarkAltTextFiles, { PluginArgs } from "../index.ts";
 
 /**
  * NOTE TO FUTURE SELF: vitest is annoying about the output of new lines on
@@ -34,6 +34,9 @@ beforeEach(() => {
 
       "./path/to/image.alt.txt":
         "This is the alt text from /path/to/image.alt.txt",
+
+      "./root/directory/path/to/image.alt.txt":
+        "This is the alt text for /path/to/image.png, relative to root/directory",
     },
     process.cwd()
   );
@@ -74,6 +77,21 @@ test("should load specific file when path is provided, from file's directory", a
 ![This is the alt text for /path/to/image.png, relative to markdown-folder](/path/to/image.png)`);
 });
 
+test("should load specific file when path is provided, from given root", async () => {
+  const result = await processMarkdown(
+    `# Hello, world!
+
+![file:./path/to/image.alt.txt](/path/to/image.png)`,
+    {
+      root: `${process.cwd()}/root/directory`,
+    }
+  );
+
+  expect(result).toBe(`# Hello, world!
+
+![This is the alt text for /path/to/image.png, relative to root/directory](/path/to/image.png)`);
+});
+
 test("should load file with same name when no path is provided", async () => {
   const result = await processMarkdown(`# Hello, world!
 
@@ -95,7 +113,9 @@ test("should fail when file does not exist", async () => {
   );
 });
 
-const processMarkdown = async (value: Compatible) => {
-  const processedTree = await remark().use(remarkAltTextFiles).process(value);
+const processMarkdown = async (value: Compatible, options?: PluginArgs) => {
+  const processedTree = await remark()
+    .use(remarkAltTextFiles, options ?? {})
+    .process(value);
   return processedTree.toString().slice(0, -1);
 };