Add mermaid-scale option to resize Mermaid images

Mermaid diagrams rendered as png or svg images are sized at their
natural size at 96 dpi, so their 16px text prints at 12pt and wide
diagrams can run past the page. fig-width scales each diagram by a
different factor, which gives every diagram a different text size.

mermaid-scale takes a percentage, such as 75%, and multiplies the
natural width and height by it, so all diagrams keep the same text
size. It can be set in the document front matter or on a single
cell, where it overrides the document value. An explicit fig-width
or fig-height still takes precedence. With mermaid-format: js the
browser sizes the diagram, so the option has no effect there.

Both the cell and front matter schemas validate the value, so a bare
number or other string fails with a clear error instead of a crash.

Author: faysou

news/changelog-1.11.md

@@ -52,6 +52,7 @@ All changes included in 1.11:
 - ([#14772](https://github.com/quarto-dev/quarto-cli/issues/14772)): Custom `language` keys now reach templates through `$quarto.language.<key>$`. A key that Quarto does not ship passed schema validation and was merged over the defaults, then discarded before templates saw it, so it expanded to an empty string with no warning. (author: @mcanouil)
 - ([#14882](https://github.com/quarto-dev/quarto-cli/issues/14882)): Fix brand font families with a word starting with a digit, such as `Source Sans 3`, not applying in `html` and `revealjs` output. The same names in `mainfont` now also apply in `revealjs`. (author: @Masad791)
 - ([#14891](https://github.com/quarto-dev/quarto-cli/issues/14891)): Fix a brand file that holds only comments, such as a commented-out `_brand.yml` template, stopping the render with `YAML value is missing`. It now prints a warning and is ignored. (author: @Masad791)
+- ([#NNNNN](https://github.com/quarto-dev/quarto-cli/pull/NNNNN)): Add a `mermaid-scale` option, such as `mermaid-scale: 75%`, that resizes Mermaid diagrams rendered as `png` or `svg` images by a percentage of their natural size, at the document or cell level. An explicit `fig-width` or `fig-height` still takes precedence. (author: @faysou)
 
 ### `dashboard`
 

src/config/constants.ts

@@ -24,6 +24,7 @@ export const kFigDpi = "fig-dpi";
 export const kFigAsp = "fig-asp";
 
 export const kMermaidFormat = "mermaid-format";
+export const kMermaidScale = "mermaid-scale";
 export const kDfPrint = "df-print";
 
 export const kCache = "cache";
@@ -170,6 +171,7 @@ export const kExecuteDefaultsKeys = [
   kFigDpi,
   kFigAsp,
   kMermaidFormat,
+  kMermaidScale,
   kDfPrint,
   kError,
   kEval,

src/config/types.ts

@@ -157,6 +157,7 @@ import {
   kMathml,
   kMergeIncludes,
   kMermaidFormat,
+  kMermaidScale,
   kNavigationBreadcrumbsLabel,
   kNavigationSiteLabel,
   kNavigationPageLabel,
@@ -544,6 +545,7 @@ export interface FormatExecute {
   [kFigDpi]?: number;
   [kFigAsp]?: number;
   [kMermaidFormat]?: "png" | "svg" | "js";
+  [kMermaidScale]?: string;
   [kDfPrint]?: "default" | "kable" | "tibble" | "paged";
   [kCache]?: true | false | "refresh" | null;
   [kFreeze]?: true | false | "auto";

src/core/handlers/mermaid.ts

@@ -35,6 +35,7 @@ import {
   kFigResponsive,
   kFigWidth,
   kMermaidFormat,
+  kMermaidScale,
 } from "../../config/constants.ts";
 import { Element } from "../deno-dom.ts";
 import { convertFromYaml } from "../lib/yaml-schema/from-yaml.ts";
@@ -59,6 +60,9 @@ object:
   properties:
     mermaid-format:
       enum: [png, svg, js]
+    mermaid-scale:
+      string:
+        pattern: "^[0-9]+(\\\\.[0-9]+)?%$"
     theme:
       anyOf:
         - null
@@ -237,6 +241,25 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
     const responsive = handlerContext.options.context.format.metadata
       ?.[kFigResponsive];
 
+    // mermaid-scale resizes the diagram's natural size; an explicit
+    // fig-width or fig-height still takes precedence.
+    const resolveScaledSize = async (svgText: string) => {
+      const size = await resolveSize(svgText, cell.options ?? {});
+      const scale = (options[kMermaidScale] ||
+        handlerContext.options.format.execute[kMermaidScale]) as
+          | string
+          | undefined;
+      if (!scale || size.explicitWidth || size.explicitHeight) {
+        return size;
+      }
+      const factor = Number(scale.slice(0, -1)) / 100;
+      return {
+        ...size,
+        widthInInches: size.widthInInches * factor,
+        heightInInches: size.heightInInches * factor,
+      };
+    };
+
     const makeSvg = async () => {
       // Extract and process SVG
       let svg = asMappedString(
@@ -350,7 +373,7 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
         const {
           widthInInches,
           heightInInches,
-        } = await resolveSize(svg.value, cell.options ?? {});
+        } = await resolveScaledSize(svg.value);
 
         return asMappedString(
           makeFigLink(sourceName, widthInInches, heightInInches, true),
@@ -364,7 +387,7 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
           svg,
           options,
           undefined,
-          new Set([kFigWidth, kFigHeight, kMermaidFormat]),
+          new Set([kFigWidth, kFigHeight, kMermaidFormat, kMermaidScale]),
         );
       }
     };
@@ -385,7 +408,7 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
       const {
         widthInInches,
         heightInInches,
-      } = await resolveSize(svgText, cell.options ?? {});
+      } = await resolveScaledSize(svgText);
 
       if (isMarkdownOutput(handlerContext.options.format, ["gfm"])) {
         return asMappedString(makeFigLink(
@@ -405,7 +428,7 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
           )),
           options,
           undefined,
-          new Set([kFigWidth, kFigHeight, kMermaidFormat]),
+          new Set([kFigWidth, kFigHeight, kMermaidFormat, kMermaidScale]),
         );
       }
     };
@@ -448,7 +471,7 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
         rawHtmlBlock.mappedString(),
         options,
         attrs,
-        new Set([kMermaidFormat]),
+        new Set([kMermaidFormat, kMermaidScale]),
       );
     };
 

src/format/formats-shared.ts

@@ -61,6 +61,7 @@ import {
   kLinkExternalNewwindow,
   kMergeIncludes,
   kMermaidFormat,
+  kMermaidScale,
   kOutput,
   kOutputDivs,
   kOutputExt,
@@ -206,6 +207,7 @@ function defaultFormat(displayName: string): Format {
       [kFigDpi]: 96,
       [kFigAsp]: undefined,
       [kMermaidFormat]: undefined,
+      [kMermaidScale]: undefined,
       [kDfPrint]: "default",
       [kError]: false,
       [kEval]: true,

src/resources/editor/tools/vs-code.mjs

@@ -17492,6 +17492,18 @@ var require_yaml_intelligence_resources = __commonJS({
             }
           },
           description: "Mermaid diagram options"
+        },
+        {
+          name: "mermaid-scale",
+          schema: {
+            string: {
+              pattern: "^[0-9]+(\\.[0-9]+)?%$"
+            }
+          },
+          description: {
+            short: "Scale for Mermaid diagrams rendered as images",
+            long: "Percentage of their natural size at which Mermaid diagrams rendered\nwith `mermaid-format: png` or `svg` are shown, for example `75%`.\nAn explicit `fig-width` or `fig-height` takes precedence.\n"
+          }
         }
       ],
       "schema/document-metadata.yml": [
@@ -24397,6 +24409,10 @@ var require_yaml_intelligence_resources = __commonJS({
         "Automatically generate the contents of a page from a list of Quarto\ndocuments or other custom data.",
         "Mermaid diagram options",
         "The mermaid built-in theme to use.",
+        {
+          short: "Scale for Mermaid diagrams rendered as images",
+          long: "Percentage of their natural size at which Mermaid diagrams rendered\nwith <code>mermaid-format: png</code> or <code>svg</code> are shown, for\nexample <code>75%</code>. An explicit <code>fig-width</code> or\n<code>fig-height</code> takes precedence."
+        },
         "List of keywords to be included in the document metadata.",
         "The document subject",
         "The subject text.",
@@ -25827,12 +25843,12 @@ var require_yaml_intelligence_resources = __commonJS({
         mermaid: "%%"
       },
       "handlers/mermaid/schema.yml": {
-        _internalId: 221295,
+        _internalId: 221618,
         type: "object",
         description: "be an object",
         properties: {
           "mermaid-format": {
-            _internalId: 221287,
+            _internalId: 221607,
             type: "enum",
             enum: [
               "png",
@@ -25847,8 +25863,14 @@ var require_yaml_intelligence_resources = __commonJS({
             ],
             exhaustiveCompletions: true
           },
+          "mermaid-scale": {
+            _internalId: 221610,
+            type: "string",
+            pattern: "^[0-9]+(\\.[0-9]+)?%$",
+            description: 'be a string that satisfies regex "^[0-9]+(\\.[0-9]+)?%$"'
+          },
           theme: {
-            _internalId: 221294,
+            _internalId: 221617,
             type: "anyOf",
             anyOf: [
               {
@@ -25869,9 +25891,9 @@ var require_yaml_intelligence_resources = __commonJS({
         },
         patternProperties: {},
         propertyNames: {
-          errorMessage: "property ${value} does not match case convention mermaid-format,theme",
+          errorMessage: "property ${value} does not match case convention mermaid-format,mermaid-scale,theme",
           type: "string",
-          pattern: "(?!(^mermaid_format$|^mermaidFormat$))",
+          pattern: "(?!(^mermaid_format$|^mermaidFormat$|^mermaid_scale$|^mermaidScale$))",
           tags: {
             "case-convention": [
               "dash-case"

src/resources/editor/tools/yaml/all-schema-definitions.json

@@ -10460,6 +10460,18 @@
         }
       },
       "description": "Mermaid diagram options"
+    },
+    {
+      "name": "mermaid-scale",
+      "schema": {
+        "string": {
+          "pattern": "^[0-9]+(\\.[0-9]+)?%$"
+        }
+      },
+      "description": {
+        "short": "Scale for Mermaid diagrams rendered as images",
+        "long": "Percentage of their natural size at which Mermaid diagrams rendered\nwith `mermaid-format: png` or `svg` are shown, for example `75%`.\nAn explicit `fig-width` or `fig-height` takes precedence.\n"
+      }
     }
   ],
   "schema/document-metadata.yml": [
@@ -17365,6 +17377,10 @@
     "Automatically generate the contents of a page from a list of Quarto\ndocuments or other custom data.",
     "Mermaid diagram options",
     "The mermaid built-in theme to use.",
+    {
+      "short": "Scale for Mermaid diagrams rendered as images",
+      "long": "Percentage of their natural size at which Mermaid diagrams rendered\nwith <code>mermaid-format: png</code> or <code>svg</code> are shown, for\nexample <code>75%</code>. An explicit <code>fig-width</code> or\n<code>fig-height</code> takes precedence."
+    },
     "List of keywords to be included in the document metadata.",
     "The document subject",
     "The subject text.",
@@ -18795,12 +18811,12 @@
     "mermaid": "%%"
   },
   "handlers/mermaid/schema.yml": {
-    "_internalId": 221295,
+    "_internalId": 221618,
     "type": "object",
     "description": "be an object",
     "properties": {
       "mermaid-format": {
-        "_internalId": 221287,
+        "_internalId": 221607,
         "type": "enum",
         "enum": [
           "png",
@@ -18815,8 +18831,14 @@
         ],
         "exhaustiveCompletions": true
       },
+      "mermaid-scale": {
+        "_internalId": 221610,
+        "type": "string",
+        "pattern": "^[0-9]+(\\.[0-9]+)?%$",
+        "description": "be a string that satisfies regex \"^[0-9]+(\\.[0-9]+)?%$\""
+      },
       "theme": {
-        "_internalId": 221294,
+        "_internalId": 221617,
         "type": "anyOf",
         "anyOf": [
           {
@@ -18837,9 +18859,9 @@
     },
     "patternProperties": {},
     "propertyNames": {
-      "errorMessage": "property ${value} does not match case convention mermaid-format,theme",
+      "errorMessage": "property ${value} does not match case convention mermaid-format,mermaid-scale,theme",
       "type": "string",
-      "pattern": "(?!(^mermaid_format$|^mermaidFormat$))",
+      "pattern": "(?!(^mermaid_format$|^mermaidFormat$|^mermaid_scale$|^mermaidScale$))",
       "tags": {
         "case-convention": [
           "dash-case"

src/resources/editor/tools/yaml/web-worker.js

@@ -8,3 +8,14 @@
           enum: ["default", "dark", "forest", "neutral"]
           description: The mermaid built-in theme to use.
   description: Mermaid diagram options
+
+- name: mermaid-scale
+  schema:
+    string:
+      pattern: "^[0-9]+(\\.[0-9]+)?%$"
+  description:
+    short: "Scale for Mermaid diagrams rendered as images"
+    long: |
+      Percentage of their natural size at which Mermaid diagrams rendered
+      with `mermaid-format: png` or `svg` are shown, for example `75%`.
+      An explicit `fig-width` or `fig-height` takes precedence.