Add basic support for serving markdown files

Author: fardjad

cli/ascaid-gfm-to-confluence.js

@@ -1,25 +1,22 @@
-import { Argument, Option, program } from "commander";
 import path from "node:path";
 import fs from "node:fs";
 import assert from "node:assert";
+import { Argument, Option, program } from "commander";
 
-import { pandocConvert } from "../index.js";
-import { readVersion } from "../index.js";
-import { ConfluenceClient } from "../index.js";
-
-const MD_TITLE_REGEX = /^#+\s+(.*)/;
-
-const isNotNullOrEmptyString = (string_) => {
-  return (
-    string_ != undefined && typeof string_ === "string" && string_.trim() !== ""
-  );
-};
+import {
+  ConfluenceClient,
+  getTitleFromMarkdown,
+  isNotNullOrEmptyString,
+  mdConvert,
+  normalizeSupportedExtnames,
+  readVersion,
+} from "../index.js";
 
 const createPageTree = async (title, filePath) => {
   const dirContents = await fs.promises.readdir(filePath);
   const files = dirContents.map((file) => ({
     name: file,
-    extension: path.extname(file),
+    normalizedExtension: normalizeSupportedExtnames(path.extname(file)),
     path: `${filePath}/${file}`,
     isDirectory: fs.lstatSync(`${filePath}/${file}`).isDirectory(),
   }));
@@ -30,22 +27,12 @@ const createPageTree = async (title, filePath) => {
     if (file.isDirectory) {
       children.push(await createPageTree(file.name, file.path));
     } else {
-      if (file.extension.toLowerCase() !== ".md") continue;
+      if (file.normalizedExtension !== ".md") continue;
       const contents = fs.readFileSync(file.path, { encoding: "utf8" });
 
-      let title = file.name.slice(
-        0,
-        Math.max(0, file.name.length - file.extension.length)
-      );
-      const firstLine = contents
-        .split(/\n\r?/)
-        .find((line) => MD_TITLE_REGEX.test(line.trim()));
-      if (firstLine != undefined) {
-        title = firstLine.match(MD_TITLE_REGEX)[1].trim();
-      }
-      const body = await pandocConvert(contents, "gfm", "html", [
-        "--wrap=none",
-      ]);
+      const title =
+        (await getTitleFromMarkdown(contents)) ?? path.parse(file.name).name;
+      const body = await mdConvert(contents);
       children.push({
         title,
         body,

cli/ascaid-serve.js

@@ -19,14 +19,16 @@ program
   .addOption(configOption)
   .addOption(attributeOption)
   .description("Start an AsciiDoc server")
-  .action(async (rootDir, { config, attribute }) => {
-    const { extensions, asciidoctorOptions } = await readConfig(
-      config,
-      attribute
-    );
-    await registerExtensions(extensions ?? [], path.resolve("."));
+  .action(
+    async (
+      rootDir,
+      { config: configFilePath, attribute: attributeOverrideKvs }
+    ) => {
+      const config = await readConfig(configFilePath, attributeOverrideKvs);
 
-    await startAsciidocServer(rootDir, asciidoctorOptions);
-  });
+      await registerExtensions(config.extensions ?? [], path.resolve("."));
+      await startAsciidocServer(rootDir, config);
+    }
+  );
 
 await program.parseAsync(process.argv);

cli/ascaid.js

@@ -1,6 +1,5 @@
 import { program } from "commander";
-import { readVersion } from "../index.js";
-import { checkPandoc } from "../index.js";
+import { readVersion, checkPandoc } from "../index.js";
 
 const version = await readVersion();
 

index.js

@@ -1,6 +1,13 @@
 export { checkPandoc, pandocConvert } from "./lib/pandoc-convert.js";
+export { mdConvert, getTitleFromMarkdown } from "./lib/md-convert.js";
 export { adocConvert } from "./lib/adoc-convert.js";
-export { invokeInDir, readConfig, readVersion } from "./lib/utils.js";
+export {
+  invokeInDir,
+  readConfig,
+  readVersion,
+  normalizeSupportedExtnames,
+  isNotNullOrEmptyString,
+} from "./lib/utils.js";
 export { registerExtensions } from "./lib/asciidoctor.js";
 export { ConfluenceClient } from "./lib/confluence-client.js";
 export {

lib/adoc-server.js

@@ -4,10 +4,17 @@ import path from "node:path";
 import http from "node:http";
 import browserSync from "browser-sync";
 
-import { fileExists, invokeInDir } from "./utils.js";
+import {
+  asciidocExtensions,
+  fileExists,
+  invokeInDir,
+  markdownExtensions,
+  normalizeSupportedExtnames,
+} from "./utils.js";
 import { adocConvert } from "./adoc-convert.js";
+import { getTitleFromMarkdown, mdConvert } from "./md-convert.js";
 
-export const createAsciidocMiddleware = (rootDir, asciidoctorOptions = {}) => {
+export const createAsciidocMiddleware = (rootDir, config = {}) => {
   const absoluteRootDir = path.resolve(rootDir);
 
   return async (request, res, next) => {
@@ -21,20 +28,37 @@ export const createAsciidocMiddleware = (rootDir, asciidoctorOptions = {}) => {
         return res.end(http.STATUS_CODES[res.statusCode]);
       }
 
-      if (/\.(adoc|asciidoc|acs)$/i.test(url.pathname)) {
-        const adocPath = path.join(absoluteRootDir, url.pathname);
-        const exists = await fileExists(adocPath);
-        if (!exists || !adocPath.startsWith(absoluteRootDir)) {
+      const extname = normalizeSupportedExtnames(path.extname(url.pathname));
+
+      if ([".md", ".adoc"].includes(extname)) {
+        const filePath = path.join(absoluteRootDir, url.pathname);
+        const exists = await fileExists(filePath);
+        if (!exists || !filePath.startsWith(absoluteRootDir)) {
           res.statusCode = 404;
 
           return res.end(http.STATUS_CODES[res.statusCode]);
         }
 
-        const adoc = await fs.readFile(adocPath, { encoding: "utf8" });
-        let html = await invokeInDir(path.dirname(adocPath), () => {
-          return adocConvert(adoc, asciidoctorOptions);
+        const contents = await fs.readFile(filePath, { encoding: "utf8" });
+        let html = await invokeInDir(path.dirname(filePath), async () => {
+          switch (extname) {
+            case ".adoc": {
+              return adocConvert(contents, config.asciidoctorOptions);
+            }
+            case ".md": {
+              const title =
+                (await getTitleFromMarkdown(contents)) ?? "Untitled";
+              return mdConvert(contents, config.markdownOptions).then(
+                (body) =>
+                  `<!DOCTYPE html><html><head><title>${title}</title></head><body>${body}</body></html>`
+              );
+            }
+            default: {
+              throw new Error(`Unsupported extension: ${extname}`);
+            }
+          }
         });
-        res.setHeader("Content-Type", "text/html");
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
         html = html.replace(
           /<\/head>/,
           `<script async src="//${request.headers.host}/browser-sync/browser-sync-client.js"></script></head>`
@@ -52,17 +76,14 @@ export const createAsciidocMiddleware = (rootDir, asciidoctorOptions = {}) => {
   };
 };
 
-export const startAsciidocServer = async (
-  rootDir = ".",
-  asciidoctorOptions = {}
-) => {
+export const startAsciidocServer = async (rootDir = ".", config = {}) => {
   const bs = browserSync.create();
 
   bs.init({
-    files: "**/*.{adoc,asciidoc,acs}",
+    files: `**/*.{${[...asciidocExtensions, ...markdownExtensions].join(",")}`,
     server: rootDir,
-    injectFileTypes: ["adoc", "asciidoc", "acs"],
-    middleware: [createAsciidocMiddleware(rootDir, asciidoctorOptions)],
+    injectFileTypes: [...asciidocExtensions, ...markdownExtensions],
+    middleware: [createAsciidocMiddleware(rootDir, config)],
     directory: true,
     open: false,
     ui: false,

lib/md-convert.js

@@ -0,0 +1,34 @@
+import { pandocConvert } from "./pandoc-convert.js";
+
+const MD_TITLE_REGEX = /^#+\s+(.*)/;
+
+const defaultMarkdownOptions = {
+  pandocReadFormat: "gfm",
+  pandocArguments: ["--wrap=none"],
+};
+
+export const getTitleFromMarkdown = (contents) => {
+  const firstHeading = contents
+    .split(/\n\r?/)
+    .find((line) => MD_TITLE_REGEX.test(line.trim()));
+
+  if (firstHeading != undefined) {
+    return firstHeading.match(MD_TITLE_REGEX)[1].trim();
+  }
+
+  return;
+};
+
+export const mdConvert = async (contents, markdownOptions = {}) => {
+  const mergedMarkdownOptions = {
+    ...defaultMarkdownOptions,
+    ...markdownOptions,
+  };
+
+  return pandocConvert(
+    contents,
+    mergedMarkdownOptions.pandocReadFormat,
+    "html",
+    mergedMarkdownOptions.pandocArguments
+  );
+};

lib/md-convert.test.js

@@ -0,0 +1,19 @@
+import { mdConvert } from "./md-convert.js";
+
+describe("mdConvert", () => {
+  describe("when config is valid", () => {
+    it("should convert input to the output", async () => {
+      const html = await mdConvert("# Hello");
+      expect(html).toBe('<h1 id="hello">Hello</h1>\n');
+    });
+  });
+
+  describe("when config is not valid", () => {
+    it("should throw an error", async () => {
+      const error = await mdConvert("# Hello", {
+        pandocReadFormat: "non-existent",
+      }).catch((error) => error);
+      expect(error).toBeInstanceOf(Error);
+    });
+  });
+});

lib/utils.js

@@ -5,6 +5,51 @@ import stripJsonComments from "strip-json-comments";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+export const markdownExtensions = [
+  "md",
+  "markdown",
+  "mdown",
+  "mkdn",
+  "mkd",
+  "mdwn",
+  "mkdown",
+  "ron",
+];
+
+export const asciidocExtensions = ["adoc", "asciidoc", "acs"];
+
+/**
+ * Normalize supported extensions
+ *
+ * @param {string} extname
+ * @return {".md" | ".adoc" | undefined} ".md" for markdown extensions, ".adoc" for asciidoc extensions. Otherwise, undefined
+ */
+export const normalizeSupportedExtnames = (extname) => {
+  if (!extname.startsWith(".")) {
+    return;
+  }
+
+  const extnameWithoutLeadingDot = extname.slice(1).toLowerCase();
+
+  if (markdownExtensions.includes(extnameWithoutLeadingDot)) {
+    return ".md";
+  }
+
+  if (asciidocExtensions.includes(extnameWithoutLeadingDot)) {
+    return ".adoc";
+  }
+
+  return;
+};
+
+export const isNotNullOrEmptyString = (maybeString) => {
+  return (
+    maybeString != undefined &&
+    typeof maybeString === "string" &&
+    maybeString.trim() !== ""
+  );
+};
+
 export const fileExists = async (path) =>
   !!(await fs.promises.stat(path).catch(() => false));