@mermaid-js/mermaid-cli 9.1.6 → 9.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mermaid-js/mermaid-cli",
-  "version": "9.1.6",
+  "version": "9.1.7",
   "description": "Command-line interface for mermaid",
   "license": "MIT",
   "repository": "git@github.com:mermaid-js/mermaid-cli.git",
@@ -24,12 +24,12 @@
   "dependencies": {
     "chalk": "^5.0.1",
     "commander": "^9.0.0",
-    "puppeteer": "^16.1.0"
+    "puppeteer": "^18.0.5"
   },
   "devDependencies": {
     "@fortawesome/fontawesome-free-webfonts": "^1.0.9",
     "mermaid": "^9.1.2",
-    "jest": "^28.1.2",
+    "jest": "^29.0.1",
     "standard": "^17.0.0",
     "yarn-upgrade-all": "^0.7.0"
   },

package/src/index.js

@@ -60,13 +60,7 @@ const getInputData = async inputFile => new Promise((resolve, reject) => {
   })
 })
 
-const convertToValidXML = html => {
-  // <br> tags in valid HTML (from innerHTML) look like <br>, but they must look like <br/> to be valid XML (such as SVG)
-  return html.replace(/<br>/gi, '<br/>')
-}
-
 async function cli () {
-// TODO: This is currently unindented to make `git diff` easier for PR reviewers.
   const commander = new Command()
   commander
     .version(pkg.version)
@@ -75,6 +69,7 @@ async function cli () {
     .option('-H, --height [height]', 'Height of the page. Optional. Default: 600', /^\d+$/, '600')
     .option('-i, --input <input>', 'Input mermaid file. Files ending in .md will be treated as Markdown and all charts (e.g. ```mermaid (...)```) will be extracted and generated. Required.')
     .option('-o, --output [output]', 'Output file. It should be either md, svg, png or pdf. Optional. Default: input + ".svg"')
+    .option('-e, --outputFormat <format>', 'Output format for the generated image. It should be either svg, png or pdf. Optional. Default: output file extension')
     .option('-b, --backgroundColor [backgroundColor]', 'Background color for pngs/svgs (not pdfs). Example: transparent, red, \'#F0F0F0\'. Optional. Default: white')
     .option('-c, --configFile [configFile]', 'JSON configuration file for mermaid. Optional')
     .option('-C, --cssFile [cssFile]', 'CSS file for the page. Optional')
@@ -86,7 +81,7 @@ async function cli () {
 
   const options = commander.opts()
 
-  let { theme, width, height, input, output, backgroundColor, configFile, cssFile, puppeteerConfigFile, scale, pdfFit, quiet } = options
+  let { theme, width, height, input, output, outputFormat, backgroundColor, configFile, cssFile, puppeteerConfigFile, scale, pdfFit, quiet } = options
 
   // check input file
   if (!(input || inputPipedFromStdin())) {
@@ -144,6 +139,7 @@ async function cli () {
     input, output, {
       puppeteerConfig,
       quiet,
+      outputFormat,
       parseMMDOptions: {
         mermaidConfig, backgroundColor, myCSS, pdfFit, viewport: { width, height, deviceScaleFactor }
       }
@@ -163,84 +159,161 @@ async function cli () {
 /**
  * Parse and render a mermaid diagram.
  *
+ * @deprecated Prefer {@link renderMermaid}, as it also returns useful metadata.
+ *
  * @param {puppeteer.Browser} browser - Puppeteer Browser
  * @param {string} definition - Mermaid diagram definition
  * @param {"svg" | "png" | "pdf"} outputFormat - Mermaid output format.
  * @param {ParseMDDOptions} [opt] - Options, see {@link ParseMDDOptions} for details.
+ *
  * @returns {Promise<Buffer>} The output file in bytes.
  */
-async function parseMMD (browser, definition, outputFormat, { viewport, backgroundColor = 'white', mermaidConfig = {}, myCSS, pdfFit } = {}) {
+async function parseMMD (...args) {
+  const { data } = await renderMermaid(...args)
+  return data
+}
+
+/**
+ * Render a mermaid diagram.
+ *
+ * @param {puppeteer.Browser} browser - Puppeteer Browser
+ * @param {string} definition - Mermaid diagram definition
+ * @param {"svg" | "png" | "pdf"} outputFormat - Mermaid output format.
+ * @param {ParseMDDOptions} [opt] - Options, see {@link ParseMDDOptions} for details.
+ * @returns {Promise<{title?: string, desc?: string, data: Buffer}>} The output file in bytes,
+ * with optional metadata.
+ */
+async function renderMermaid (browser, definition, outputFormat, { viewport, backgroundColor = 'white', mermaidConfig = {}, myCSS, pdfFit } = {}) {
   const page = await browser.newPage()
-  if (viewport) {
-    await page.setViewport(viewport)
-  }
-  const mermaidHTMLPath = path.join(__dirname, '..', 'index.html')
-  await page.goto(url.pathToFileURL(mermaidHTMLPath))
-  await page.$eval('body', (body, backgroundColor) => {
-    body.style.background = backgroundColor
-  }, backgroundColor)
-  await page.$eval('#container', (container, definition, mermaidConfig, myCSS, backgroundColor) => {
-    container.textContent = definition
-    window.mermaid.initialize(mermaidConfig)
-    // should throw an error if mmd diagram is invalid
-    try {
-      window.mermaid.initThrowsErrors(undefined, container)
-    } catch (error) {
-      if (error instanceof Error) {
-        // mermaid-js doesn't currently throws JS Errors, but let's leave this
-        // here in case it does in the future
-        throw error
+  try {
+    if (viewport) {
+      await page.setViewport(viewport)
+    }
+    const mermaidHTMLPath = path.join(__dirname, '..', 'index.html')
+    await page.goto(url.pathToFileURL(mermaidHTMLPath))
+    await page.$eval('body', (body, backgroundColor) => {
+      body.style.background = backgroundColor
+    }, backgroundColor)
+    const metadata = await page.$eval('#container', (container, definition, mermaidConfig, myCSS, backgroundColor) => {
+      container.textContent = definition
+      window.mermaid.initialize(mermaidConfig)
+      // should throw an error if mmd diagram is invalid
+      try {
+        window.mermaid.initThrowsErrors(undefined, container)
+      } catch (error) {
+        if (error instanceof Error) {
+          // mermaid-js doesn't currently throws JS Errors, but let's leave this
+          // here in case it does in the future
+          throw error
+        } else {
+          throw new Error(error?.message ?? 'Unknown mermaid render error')
+        }
+      }
+
+      const svg = container.getElementsByTagName?.('svg')?.[0]
+      if (svg?.style) {
+        svg.style.backgroundColor = backgroundColor
       } else {
-        throw new Error(error?.message ?? 'Unknown mermaid render error')
+        warn('svg not found. Not applying background color.')
+      }
+      if (myCSS) {
+        // add CSS as a <svg>...<style>... element
+        // see https://developer.mozilla.org/en-US/docs/Web/API/SVGStyleElement
+        const style = document.createElementNS('http://www.w3.org/2000/svg', 'style')
+        style.appendChild(document.createTextNode(myCSS))
+        svg.appendChild(style)
       }
-    }
 
-    const svg = container.getElementsByTagName?.('svg')?.[0]
-    if (svg?.style) {
-      svg.style.backgroundColor = backgroundColor
-    } else {
-      warn('svg not found. Not applying background color.')
-      return
-    }
-    if (myCSS) {
-      // add CSS as a <svg>...<style>... element
-      // see https://developer.mozilla.org/en-US/docs/Web/API/SVGStyleElement
-      const style = document.createElementNS('http://www.w3.org/2000/svg', 'style')
-      style.appendChild(document.createTextNode(myCSS))
-      svg.appendChild(style)
-    }
-  }, definition, mermaidConfig, myCSS, backgroundColor)
+      // Finds SVG metadata for accessibility purposes
+      /** SVG title */
+      let title = null
+      // If <title> exists, it must be the first child Node,
+      // see https://www.w3.org/TR/SVG11/struct.html#DescriptionAndTitleElements
+      /* global SVGTitleElement, SVGDescElement */ // These exist in browser-based code
+      if (svg.firstChild instanceof SVGTitleElement) {
+        title = svg.firstChild.textContent
+      }
+      /** SVG description. According to SVG spec, we should use the first one we find */
+      let desc = null
+      for (const svgNode of svg.children) {
+        if (svgNode instanceof SVGDescElement) {
+          desc = svgNode.textContent
+        }
+      }
+      return {
+        title, desc
+      }
+    }, definition, mermaidConfig, myCSS, backgroundColor)
 
-  if (outputFormat === 'svg') {
-    const svg = await page.$eval('#container', (container) => {
-      return container.innerHTML
-    })
-    const svgXML = convertToValidXML(svg)
-    return Buffer.from(svgXML, 'utf8')
-  } else if (outputFormat === 'png') {
-    const clip = await page.$eval('svg', svg => {
-      const react = svg.getBoundingClientRect()
-      return { x: Math.floor(react.left), y: Math.floor(react.top), width: Math.ceil(react.width), height: Math.ceil(react.height) }
-    })
-    await page.setViewport({ ...viewport, width: clip.x + clip.width, height: clip.y + clip.height })
-    return await page.screenshot({ clip, omitBackground: backgroundColor === 'transparent' })
-  } else { // pdf
-    if (pdfFit) {
+    if (outputFormat === 'svg') {
+      const svgXML = await page.$eval('svg', (svg) => {
+        // SVG might have HTML <foreignObject> that are not valid XML
+        // E.g. <br> must be replaced with <br/>
+        // Luckily the DOM Web API has the XMLSerializer for this
+        // eslint-disable-next-line no-undef
+        const xmlSerializer = new XMLSerializer()
+        return xmlSerializer.serializeToString(svg)
+      })
+      return {
+        ...metadata,
+        data: Buffer.from(svgXML, 'utf8')
+      }
+    } else if (outputFormat === 'png') {
       const clip = await page.$eval('svg', svg => {
         const react = svg.getBoundingClientRect()
-        return { x: react.left, y: react.top, width: react.width, height: react.height }
-      })
-      return await page.pdf({
-        omitBackground: backgroundColor === 'transparent',
-        width: (Math.ceil(clip.width) + clip.x * 2) + 'px',
-        height: (Math.ceil(clip.height) + clip.y * 2) + 'px',
-        pageRanges: '1-1'
-      })
-    } else {
-      return await page.pdf({
-        omitBackground: backgroundColor === 'transparent'
+        return { x: Math.floor(react.left), y: Math.floor(react.top), width: Math.ceil(react.width), height: Math.ceil(react.height) }
       })
+      await page.setViewport({ ...viewport, width: clip.x + clip.width, height: clip.y + clip.height })
+      return {
+        ...metadata,
+        data: await page.screenshot({ clip, omitBackground: backgroundColor === 'transparent' })
+      }
+    } else { // pdf
+      if (pdfFit) {
+        const clip = await page.$eval('svg', svg => {
+          const react = svg.getBoundingClientRect()
+          return { x: react.left, y: react.top, width: react.width, height: react.height }
+        })
+        return {
+          ...metadata,
+          data: await page.pdf({
+            omitBackground: backgroundColor === 'transparent',
+            width: (Math.ceil(clip.width) + clip.x * 2) + 'px',
+            height: (Math.ceil(clip.height) + clip.y * 2) + 'px',
+            pageRanges: '1-1'
+          })
+        }
+      } else {
+        return {
+          ...metadata,
+          data: await page.pdf({
+            omitBackground: backgroundColor === 'transparent'
+          })
+        }
+      }
     }
+  } finally {
+    await page.close()
+  }
+}
+
+/**
+ * Creates a markdown image syntax.
+ *
+ * @param {object} params - Parameters.
+ * @param {string} params.url - Path to image.
+ * @param {string} params.alt - Image alt text, required.
+ * @param {string} [params.title] - Image title text.
+ * @returns {`![${string}](${string})`} The markdown image text.
+ */
+function markdownImage ({ url, title, alt }) {
+  // we can't use String.prototype.replaceAll since it's not supported in Node v14
+  const altEscaped = alt.replace(/[[\]\\]/g, '\\$&')
+  if (title) {
+    const titleEscaped = title.replace(/["\\]/g, '\\$&')
+    return `![${altEscaped}](${url} "${titleEscaped}")`
+  } else {
+    return `![${altEscaped}](${url})`
   }
 }
 
@@ -254,57 +327,80 @@ async function parseMMD (browser, definition, outputFormat, { viewport, backgrou
  * @param {Object} [opts] - Options
  * @param {puppeteer.LaunchOptions} [opts.puppeteerConfig] - Puppeteer launch options.
  * @param {boolean} [opts.quiet] - If set, suppress log output.
+ * @param {"svg" | "png" | "pdf"} [opts.outputFormat] - Mermaid output format.
+ * Defaults to `output` extension. Overrides `output` extension if set.
  * @param {ParseMDDOptions} [opts.parseMMDOptions] - Options to pass to {@link parseMMDOptions}.
  */
-async function run (input, output, { puppeteerConfig = {}, quiet = false, parseMMDOptions } = {}) {
+async function run (input, output, { puppeteerConfig = {}, quiet = false, outputFormat, parseMMDOptions } = {}) {
   const info = message => {
     if (!quiet) {
       console.info(message)
     }
   }
 
-  const mermaidChartsInMarkdown = /^```(?:mermaid)(\r?\n([\s\S]*?))```$/
+  const mermaidChartsInMarkdown = /^\s*```(?:mermaid)(\r?\n([\s\S]*?))```\s*$/
   const mermaidChartsInMarkdownRegexGlobal = new RegExp(mermaidChartsInMarkdown, 'gm')
-  const mermaidChartsInMarkdownRegex = new RegExp(mermaidChartsInMarkdown)
   const browser = await puppeteer.launch(puppeteerConfig)
   try {
-  // TODO: indent this (currently unindented to make `git diff` smaller)
+    if (!outputFormat) {
+      outputFormat = path.extname(output).replace('.', '')
+    }
+    if (outputFormat === 'md') {
+      // fallback to svg in case no outputFormat is given and output file is MD
+      outputFormat = 'svg'
+    }
+    if (!/(?:svg|png|pdf)$/.test(outputFormat)) {
+      throw new Error('Output format must be one of "svg", "png" or "pdf"')
+    }
+
     const definition = await getInputData(input)
     if (/\.md$/.test(input)) {
-      const diagrams = []
-      const outDefinition = definition.replace(mermaidChartsInMarkdownRegexGlobal, (mermaidMd) => {
-        const md = mermaidChartsInMarkdownRegex.exec(mermaidMd)[1]
+      const imagePromises = []
+      for (const mermaidCodeblockMatch of definition.matchAll(mermaidChartsInMarkdownRegexGlobal)) {
+        const mermaidDefinition = mermaidCodeblockMatch[1]
 
         // Output can be either a template image file, or a `.md` output file.
         //   If it is a template image file, use that to created numbered diagrams
         //     I.e. if "out.png", use "out-1.png", "out-2.png", etc
         //   If it is an output `.md` file, use that to base .svg numbered diagrams on
         //     I.e. if "out.md". use "out-1.svg", "out-2.svg", etc
-        const outputFile = output.replace(/(\.(md|png|svg|pdf))$/, `-${diagrams.length + 1}$1`).replace(/(\.md)$/, '.svg')
+        const outputFile = output.replace(/(\.(md|png|svg|pdf))$/, `-${imagePromises.length + 1}$1`).replace(/(\.md)$/, `.${outputFormat}`)
         const outputFileRelative = `./${path.relative(path.dirname(path.resolve(output)), path.resolve(outputFile))}`
-        diagrams.push([outputFile, md])
-        return `![diagram](${outputFileRelative})`
-      })
 
-      if (diagrams.length) {
-        info(`Found ${diagrams.length} mermaid charts in Markdown input`)
-        await Promise.all(diagrams.map(async ([imgFile, md]) => {
-          const data = await parseMMD(browser, md, path.extname(imgFile).replace('.', ''), parseMMDOptions)
-          await fs.promises.writeFile(imgFile, data)
-          info(` ✅ ${imgFile}`)
-        })
-        )
+        const imagePromise = (async () => {
+          const { title, desc, data } = await renderMermaid(browser, mermaidDefinition, outputFormat, parseMMDOptions)
+          await fs.promises.writeFile(outputFile, data)
+          info(` ✅ ${outputFileRelative}`)
+
+          return {
+            url: outputFileRelative,
+            title,
+            alt: desc
+          }
+        })()
+        imagePromises.push(imagePromise)
+      }
+
+      if (imagePromises.length) {
+        info(`Found ${imagePromises.length} mermaid charts in Markdown input`)
       } else {
         info('No mermaid charts found in Markdown input')
       }
 
+      const images = await Promise.all(imagePromises)
+
       if (/\.md$/.test(output)) {
+        const outDefinition = definition.replace(mermaidChartsInMarkdownRegexGlobal, (_mermaidMd) => {
+          // pop first image from front of array
+          const { url, title, alt } = images.shift()
+          return markdownImage({ url, title, alt: alt || 'diagram' })
+        })
         await fs.promises.writeFile(output, outDefinition, 'utf-8')
         info(` ✅ ${output}`)
       }
     } else {
       info('Generating single mermaid chart')
-      const data = await parseMMD(browser, definition, path.extname(output).replace('.', ''), parseMMDOptions)
+      const data = await parseMMD(browser, definition, outputFormat, parseMMDOptions)
       await fs.promises.writeFile(output, data)
     }
   } finally {
@@ -312,4 +408,4 @@ async function run (input, output, { puppeteerConfig = {}, quiet = false, parseM
   }
 }
 
-export { run, parseMMD, cli, error }
+export { run, renderMermaid, parseMMD, cli, error }