Add mermaid-scale option to resize Mermaid images

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)
+- ([#15192](https://github.com/quarto-dev/quarto-cli/pull/15192)): 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/yaml-intelligence-resources.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/schema/document-mermaid.yml

@@ -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.