Feature: allow `mmdc` to output Markdown files

[mermaid-js]

Feature: allow `mmdc` to output Markdown files

[CreativeCactus]

I will get someone on it shortly, either myself or a colleague :)
It's been a busy month.

[MindaugasLaganeckas]

@CreativeCactus : would you consider working on PR? :)

[nicojs]

This feature would be a game-changer for anyone who is looking to add diagrams to their readme.md file (running npx mmdc -i readme.template.md -o readme.md).

[nicojs]

Work around that I use:

tasks/generate-md.mjs

// @ts-check
import { promises as fs } from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { execFile } from "child_process";
import os from "os";

const dirName = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const imageDir = path.join(dirName, "img");
const templatePostFix = ".template.md";

const files = await fs.readdir(dirName, { withFileTypes: true });

const mermaidRegexGlobal = /```mermaid\s*([\s\S]+?)\s*```/g;
const mermaidRegex = /```mermaid\s*([\s\S]+?)\s*```/;

await Promise.all(
  files
    .filter((entry) => entry.isFile())
    .filter(({ name }) => name.endsWith(templatePostFix))
    .map(async ({ name: fileName }) => {
      const imgSubDir = fileName.slice(0, -templatePostFix.length);
      const outDir = path.join(imageDir, imgSubDir);
      await fs.mkdir(outDir, { recursive: true });
      const content = await fs.readFile(fileName, "utf-8");
      const diagrams = [];
      const output = content.replaceAll(mermaidRegexGlobal, (mermaidMd) => {
        const md = mermaidRegex.exec(mermaidMd)[1];
        const imgUrl = `img/${imgSubDir}/diagram-${diagrams.length}.png`;
        diagrams.push([imgUrl, md]);
        return `![diagram](${imgUrl})`;
      });
      await Promise.all(
        diagrams.map(async ([imgFile, md], index) => {
          const tmpFileName = `__temp__${index}.mmdc`;
          await fs.writeFile(tmpFileName, md, "utf-8");
          await execMermaidCli(
            "-i",
            tmpFileName,
            "-o",
            path.resolve(dirName, imgFile)
          );
          await fs.rm(tmpFileName);
        })
      );

      const outFile = `${fileName.slice(0, -templatePostFix.length)}.md`;
      await fs.writeFile(path.resolve(dirName, outFile), output, 'utf-8');
      console.log(`✅ ${outFile} (${diagrams.length} diagram${diagrams.length === 1? '': 's'})`);
    })
);

async function execMermaidCli(...args) {
  return new Promise((res, rej) => {
    execFile(
      os.platform() === "win32" ? "npx.cmd" : "npx",
      ["mmdc", ...args],
      (err, stdout, stderr) => {
        if (err) {
          console.log(stdout);
          console.error(stderr);
          rej(err);
        } else {
          res();
        }
      }
    );
  });
}

I might be tempted to pick this one up, just because of how useful I think this feature is 😁