@imontene/mdrender 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Cambios
 
+## 2.2.0 — 2026-10-15
+
+- **Autoajuste de diagramas de flujo Mermaid** (`flowchart`/`graph`): cada diagrama se dibuja
+  con varios anchos de ajuste de etiquetas y se elige el que imprime el texto más grande (a igual
+  legibilidad, el más bajo), nunca más pequeño que tal como está escrito. Si sigue por debajo del
+  75 % de su tamaño, se prueba el otro eje (`LR` → `TB`, `TD` → `LR`) y se gira si gana al menos
+  15 puntos. En el banco de pruebas, la escala media del texto pasa de 0,80 a 0,98 y ningún
+  diagrama queda por debajo de 0,6.
+  - `--mermaid-flip never` (`mermaidFlip`) conserva la dirección; `--no-mermaid-autofit`
+    (`mermaidAutofit: false`) lo desactiva. Se respetan los diagramas con `%%{init}%%` o
+    `config:` propios.
+  - `-v` informa la elección por diagrama; aviso si un diagrama se imprime por debajo del 50 %.
+- Un título seguido de un diagrama o una imagen ya no queda solo al pie de una página: pasa con
+  ellos a la siguiente.
+- `npm run bench:mermaid [-- archivo.md]` compara los diagramas de un documento con y sin
+  autoajuste.
+
+## 2.1.0 — 2026-10-15
+
+- `mdrender doctor`: revisa instalación (versión, Node.js, `PATH`), navegador (cuál y por qué,
+  arranque y versión, sandbox), una conversión real de prueba, el `mdrender.config.json`
+  aplicado (errores, opciones mal escritas, valores efectivos), la caché de `setup` y el proxy.
+  `--quick`, `--json`; código 1 si encuentra un problema.
+- Mejor uso de la página:
+  - Los bloques de código largos se parten entre páginas (al menos 4 líneas a cada lado) en
+    vez de saltar enteros y dejar hasta media página en blanco; los de hasta 12 líneas siguen
+    juntos.
+  - `--density compact` (o `density: compact`): interlineado y espacios más ajustados.
+  - `--font-size <tamaño>` (o `fontSize`): tamaño del texto, por defecto 10.5pt.
+  - Mermaid usa el tamaño de letra del documento (antes 16 px) y los diagramas de secuencia no
+    repiten los actores al pie.
+  - Imágenes y diagramas más altos que la página se reducen para caber en una sola.
+
 ## 2.0.0 — 2026-10-13
 
 - Márgenes por lado: `--margin-top`, `--margin-right`, `--margin-bottom`, `--margin-left`

package/README.md

@@ -89,14 +89,39 @@ mdrender docs/ -o pdf/ --watch
 # Vista previa en el navegador que se recarga sola al guardar
 mdrender preview documento.md
 
+# Más contenido por página
+mdrender documento.md --density compact --font-size 10pt
+
 # Tema oscuro, o un CSS propio que reemplaza el tema
 mdrender documento.md --theme dark
 mdrender documento.md --theme mi-tema.css
 
 # Descargar un navegador si no tienes Chrome, Edge ni Chromium
 mdrender setup
+
+# Diagnóstico: instalación, navegador, configuración y una conversión de prueba
+mdrender doctor
+```
+
+### Si algo no funciona: `mdrender doctor`
+
+Revisa la versión y el Node.js, si `mdrender` está en el `PATH`, qué navegador se usa (y por
+qué), lo arranca y convierte un documento de prueba con una ecuación y un diagrama, e indica
+qué `mdrender.config.json` se aplica, con sus opciones mal escritas y los valores efectivos.
+Cada problema viene con su solución sugerida; termina con código 1 si encuentra alguno.
+
+```text
+[ok]   mdrender         2.0.0, npm package (/usr/lib/node_modules/@imontene/mdrender)
+[ok]   Node.js          22.23.3
+[warn] PATH             the mdrender command is not in any PATH folder
+                        -> add its folder to PATH (for npm: the output of `npm prefix -g`…)
+[ok]   Browser          C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
+[ok]   Test conversion  PDF with an equation and a Mermaid diagram in 1840 ms
 ```
 
+`--quick` omite el arranque del navegador y la conversión; `--json` produce el informe en JSON
+para compartirlo.
+
 En Windows (PowerShell o CMD) los comandos son idénticos:
 
 ```powershell
@@ -109,35 +134,39 @@ equipo); `--port` fija el puerto y `--no-open` no abre el navegador.
 
 ### Opciones
 
-| Opción                        | Descripción                                                 | Por defecto        |
-| ----------------------------- | ----------------------------------------------------------- | ------------------ |
-| `-o, --output <ruta>`         | Archivo de salida, o carpeta con varios archivos            | junto al `.md`     |
-| `-f, --format <pdf\|html>`    | Formato de salida                                           | `pdf`              |
-| `--page-size <tamaño>`        | `Letter`, `A4`, `Legal` (también `A3`, `A5`, `Tabloid`)     | `Letter`           |
-| `--margin <valor>`            | Las cuatro márgenes como en CSS: `10mm`, `15mm 20mm`…       | `10mm`             |
-| `--margin-top <medida>`       | Margen superior, p. ej. `15mm` (prevalece sobre `--margin`) | `10mm`             |
-| `--margin-right <medida>`     | Margen derecho                                              | `10mm`             |
-| `--margin-bottom <medida>`    | Margen inferior                                             | `10mm`             |
-| `--margin-left <medida>`      | Margen izquierdo                                            | `10mm`             |
-| `--orientation <orientación>` | `portrait` (vertical) o `landscape` (horizontal)            | `portrait`         |
-| `--landscape`                 | Atajo de `--orientation landscape`                          | —                  |
-| `--toc`                       | Tabla de contenidos al inicio (o donde pongas `[[toc]]`)    | —                  |
-| `--toc-depth <n>`             | Nivel de título más profundo en la tabla de contenidos      | `3`                |
-| `--header <texto>`            | Encabezado de página (ver abajo)                            | —                  |
-| `--footer <texto>`            | Pie de página (ver abajo)                                   | `{page} / {pages}` |
-| `--no-page-numbers`           | Sin el pie con números de página                            | —                  |
-| `--theme <light\|dark\|css>`  | `light`, `dark` o un `.css` que reemplaza el tema           | `light`            |
-| `--css <archivo.css>`         | CSS adicional (se puede repetir)                            | —                  |
-| `--mermaid-theme <tema>`      | `default`, `neutral`, `dark`, `forest`, `base`              | `neutral` / `dark` |
-| `--lang <código>`             | Idioma del documento; `en` para inglés (`pt`, `fr`, `de`…)  | `es`               |
-| `--title <texto>`             | Título del documento (muestra un bloque de título)          | primer `# título`  |
-| `--config <archivo>`          | Archivo de configuración                                    | el más cercano     |
-| `--no-config`                 | Ignorar `mdrender.config.json`                              | —                  |
-| `--browser <ruta>`            | Ruta a Chrome/Edge/Chromium (o variable `MDRENDER_BROWSER`) | autodetección      |
-| `--allow-remote`              | Permitir que el PDF descargue imágenes/CSS de internet      | bloqueado          |
-| `-w, --watch`                 | Regenerar al guardar                                        | —                  |
-| `-q, --quiet`                 | Mostrar solo advertencias y errores                         | —                  |
-| `-v, --verbose`               | Mostrar también configuración, navegador y tiempos          | —                  |
+| Opción                         | Descripción                                                          | Por defecto        |
+| ------------------------------ | -------------------------------------------------------------------- | ------------------ |
+| `-o, --output <ruta>`          | Archivo de salida, o carpeta con varios archivos                     | junto al `.md`     |
+| `-f, --format <pdf\|html>`     | Formato de salida                                                    | `pdf`              |
+| `--page-size <tamaño>`         | `Letter`, `A4`, `Legal` (también `A3`, `A5`, `Tabloid`)              | `Letter`           |
+| `--margin <valor>`             | Las cuatro márgenes como en CSS: `10mm`, `15mm 20mm`…                | `10mm`             |
+| `--margin-top <medida>`        | Margen superior, p. ej. `15mm` (prevalece sobre `--margin`)          | `10mm`             |
+| `--margin-right <medida>`      | Margen derecho                                                       | `10mm`             |
+| `--margin-bottom <medida>`     | Margen inferior                                                      | `10mm`             |
+| `--margin-left <medida>`       | Margen izquierdo                                                     | `10mm`             |
+| `--orientation <orientación>`  | `portrait` (vertical) o `landscape` (horizontal)                     | `portrait`         |
+| `--landscape`                  | Atajo de `--orientation landscape`                                   | —                  |
+| `--toc`                        | Tabla de contenidos al inicio (o donde pongas `[[toc]]`)             | —                  |
+| `--toc-depth <n>`              | Nivel de título más profundo en la tabla de contenidos               | `3`                |
+| `--header <texto>`             | Encabezado de página (ver abajo)                                     | —                  |
+| `--footer <texto>`             | Pie de página (ver abajo)                                            | `{page} / {pages}` |
+| `--no-page-numbers`            | Sin el pie con números de página                                     | —                  |
+| `--density <densidad>`         | `normal` o `compact` (menos espacio entre líneas y bloques)          | `normal`           |
+| `--font-size <tamaño>`         | Tamaño del texto en `pt` o `px`, de 6 a 24 pt; p. ej. `10pt`         | `10.5pt`           |
+| `--theme <light\|dark\|css>`   | `light`, `dark` o un `.css` que reemplaza el tema                    | `light`            |
+| `--css <archivo.css>`          | CSS adicional (se puede repetir)                                     | —                  |
+| `--mermaid-theme <tema>`       | `default`, `neutral`, `dark`, `forest`, `base`                       | `neutral` / `dark` |
+| `--mermaid-flip <auto\|never>` | Si el autoajuste puede girar un diagrama de flujo de eje (ver abajo) | `auto`             |
+| `--no-mermaid-autofit`         | Dibujar los diagramas de flujo tal como están escritos               | —                  |
+| `--lang <código>`              | Idioma del documento; `en` para inglés (`pt`, `fr`, `de`…)           | `es`               |
+| `--title <texto>`              | Título del documento (muestra un bloque de título)                   | primer `# título`  |
+| `--config <archivo>`           | Archivo de configuración                                             | el más cercano     |
+| `--no-config`                  | Ignorar `mdrender.config.json`                                       | —                  |
+| `--browser <ruta>`             | Ruta a Chrome/Edge/Chromium (o variable `MDRENDER_BROWSER`)          | autodetección      |
+| `--allow-remote`               | Permitir que el PDF descargue imágenes/CSS de internet               | bloqueado          |
+| `-w, --watch`                  | Regenerar al guardar                                                 | —                  |
+| `-q, --quiet`                  | Mostrar solo advertencias y errores                                  | —                  |
+| `-v, --verbose`                | Mostrar también configuración, navegador y tiempos                   | —                  |
 
 **Página**: por defecto hoja **Letter vertical con márgenes de 10 mm**. Las medidas aceptan
 `mm`, `cm`, `in` o `px`. `--margin` fija las cuatro márgenes a la vez y `--margin-top`,
@@ -146,6 +175,16 @@ equipo); `--port` fija el puerto y `--no-open` no abre el navegador.
 El encabezado y el pie se dibujan dentro de las márgenes superior e inferior: con menos de
 10 mm pueden tocar el texto y mdrender lo advierte.
 
+**Aprovechar la página**: `--density compact` reduce interlineado, espacios entre párrafos y
+títulos, y `--font-size 10pt` achica el texto (los diagramas Mermaid siguen el mismo tamaño).
+Juntos ahorran entre un 15 y un 25 % de páginas. Además, siempre:
+
+- Los bloques de código largos continúan en la página siguiente (con al menos 4 líneas a cada
+  lado del corte) en lugar de saltar enteros y dejar un hueco; los de hasta 12 líneas no se
+  parten.
+- Las imágenes y diagramas más altos que la página se reducen para caber en una sola.
+- Los diagramas de secuencia no repiten los actores al pie.
+
 **Encabezado y pie**: texto con marcadores `{page}`, `{pages}`, `{title}`, `{author}` y
 `{date}`; `|` separa columnas izquierda, centro y derecha. Ejemplos:
 `--header "{title} | | {date}"`, `--footer "Confidencial | {page} de {pages}"`.
@@ -176,6 +215,8 @@ header: "{title} | | {date}"
   "pageSize": "Letter",
   "margin": "15mm",
   "marginLeft": "25mm",
+  "density": "compact",
+  "fontSize": "10pt",
   "css": "estilos/empresa.css"
 }
 ```
@@ -198,6 +239,25 @@ fecha). Las rutas de `css` y `theme` son relativas al archivo donde aparecen.
 - Si una fórmula o diagrama tiene un error, el documento se genera igual con una caja roja en
   su lugar, se informa `error: archivo.md:LÍNEA: mensaje` y el comando termina con código `2`.
 
+**Autoajuste de diagramas de flujo**: en el PDF, un diagrama más ancho que la columna o más alto
+que la página se reduce entero, y su texto puede quedar diminuto. Por eso mdrender dibuja cada
+`flowchart`/`graph` con varios anchos de ajuste de las etiquetas y se queda con el que imprime el
+texto más grande; a igual legibilidad, el que ocupa menos alto. Nunca lo imprime más pequeño que
+tal como está escrito.
+
+- Si el diagrama sigue por debajo del 75 % de su tamaño, prueba además el otro eje (`LR` → `TB`,
+  o `TD` → `LR`) y lo gira si gana al menos 15 puntos. Una cadena horizontal de 8 cajas, por
+  ejemplo, pasa de imprimirse al 37 % a su tamaño real. `--mermaid-flip never` (o
+  `mermaidFlip: never`) conserva siempre la dirección escrita.
+- No se tocan los diagramas con configuración propia (`%%{init: …}%%` o `config:` en su front
+  matter) ni los de otros tipos (secuencia, torta, clases…).
+- `-v` informa la elección de cada diagrama; si alguno queda por debajo del 50 %, mdrender avisa:
+  conviene partirlo o acortar sus etiquetas.
+- `--no-mermaid-autofit` (o `mermaidAutofit: false`) lo desactiva.
+
+Un título seguido de un diagrama o una imagen pasa con ellos a la página siguiente cuando no
+caben, en lugar de quedar solo al pie de la anterior.
+
 ## Más Markdown
 
 - **Alertas** estilo GitHub: `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`,

package/dist/assets/density-compact.css

@@ -0,0 +1,74 @@
+/* mdrender compact density (--density compact): loaded after the theme, tightens vertical spacing. */
+
+body {
+  line-height: 1.5;
+}
+
+p,
+ul,
+ol,
+blockquote,
+pre,
+table,
+dl {
+  margin-bottom: 0.8em;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  margin: 1.3em 0 0.5em;
+}
+
+h1 {
+  font-size: 1.9em;
+}
+
+h2 {
+  font-size: 1.4em;
+}
+
+h3 {
+  font-size: 1.18em;
+}
+
+li + li {
+  margin-top: 0.15em;
+}
+
+pre {
+  padding: 0.7em 0.9em;
+}
+
+th,
+td {
+  padding: 0.35em 0.7em;
+}
+
+.math-display {
+  margin: 0.8em 0;
+}
+
+.mermaid-diagram {
+  margin: 0.9em 0;
+}
+
+.doc-header {
+  margin-bottom: 1.5em;
+}
+
+.toc {
+  margin-bottom: 1.5em;
+  padding: 0.8em 1.2em;
+}
+
+hr {
+  margin: 1.5em 0;
+}
+
+hr.footnotes-sep {
+  margin: 1.8em 0 0.8em;
+}

package/dist/assets/theme.css

@@ -243,6 +243,14 @@ pre {
   background: var(--color-subtle-bg);
   white-space: pre-wrap;
   overflow-wrap: anywhere;
+  /* Long listings may continue on the next page, keeping a few lines on each side. */
+  break-inside: auto;
+  orphans: 4;
+  widows: 4;
+}
+
+/* Short blocks (marked by mdrender) stay on one page. */
+pre.keep-together {
   break-inside: avoid;
 }
 
@@ -335,6 +343,32 @@ div.math-error {
   height: auto;
 }
 
+/*
+ * In the PDF, images and diagrams are scaled down to fit the page height (mdrender sets
+ * --page-content-height), so they are never cut across pages.
+ */
+@media print {
+  img,
+  .mermaid-diagram svg {
+    max-height: calc(var(--page-content-height) - 6mm);
+  }
+
+  /* Next to its heading: leave room for it (HEADING_ALLOWANCE_EM in render/mermaid.ts). */
+  .keep-with-heading img,
+  .keep-with-heading .mermaid-diagram svg {
+    max-height: calc(var(--page-content-height) - 6mm - 5rem);
+  }
+}
+
+/* A heading and the diagram or image right after it go to the same page. */
+.keep-with-heading {
+  break-inside: avoid;
+}
+
+.markdown-body > .keep-with-heading:first-child > :first-child {
+  margin-top: 0;
+}
+
 /* Mermaid's HTML labels are <p>/<span> inside <foreignObject>: keep document styles out. */
 .mermaid-diagram foreignObject p {
   margin: 0;

package/dist/assets.js

@@ -85,7 +85,11 @@ export const MONO_STYLESHEETS = [
 ];
 export const KATEX_CSS = "katex/dist/katex.min.css";
 export const MERMAID_JS = "mermaid/dist/mermaid.min.js";
-export const THEMES = ["mdrender/assets/theme.css", "mdrender/assets/theme-dark.css"];
+export const THEMES = [
+    "mdrender/assets/theme.css",
+    "mdrender/assets/theme-dark.css",
+    "mdrender/assets/density-compact.css",
+];
 export const PACKAGE_JSON = "mdrender/package.json";
 /** Fonts referenced by a stylesheet as url(...woff2), as asset keys. */
 export function woff2References(cssKey, css) {

package/dist/cli.js

@@ -1,5 +1,6 @@
 import { Command, CommanderError, Option } from "commander";
 import { setup } from "./browser/setup.js";
+import { formatReport, runDoctor } from "./doctor.js";
 import { MdRenderError } from "./errors.js";
 import { ExitCode } from "./exit-codes.js";
 import { expandInputs, planOutputs } from "./inputs.js";
@@ -24,9 +25,13 @@ const DOCUMENT_FLAGS = [
     "header",
     "footer",
     "pageNumbers",
+    "density",
+    "fontSize",
     "css",
     "theme",
     "mermaidTheme",
+    "mermaidAutofit",
+    "mermaidFlip",
     "lang",
     "title",
 ];
@@ -52,9 +57,13 @@ function addDocumentOptions(command) {
         .option("--header <text>", 'page header, e.g. "{title} | | {date}"')
         .option("--footer <text>", 'page footer (default: "{page} / {pages}")')
         .option("--no-page-numbers", "no default page-number footer")
+        .option("--density <density>", "normal or compact (tighter spacing) (default: normal)")
+        .option("--font-size <size>", "text size, e.g. 10pt or 11pt (default: 10.5pt)")
         .option("--theme <theme>", "light, dark, or a .css file replacing the theme (default: light)")
         .option("--css <file>", "extra stylesheet (repeatable)", collect)
         .option("--mermaid-theme <theme>", `Mermaid theme: ${MERMAID_THEMES.join(", ")} (default: neutral; dark with --theme dark)`)
+        .option("--no-mermaid-autofit", "draw flowcharts exactly as written (no layout search)")
+        .option("--mermaid-flip <mode>", "auto: turn a flowchart to the other axis if its text prints too small; never (default: auto)")
         .option("--lang <tag>", "document language, e.g. es or en (default: es)")
         .option("--title <text>", "document title (shown as a title block)")
         .option("--config <file>", "config file (default: nearest mdrender.config.json)")
@@ -80,6 +89,7 @@ function buildRenderProgram(io) {
 Commands:
   mdrender preview <file>  live HTML preview in the browser (see: mdrender preview --help)
   mdrender setup           download a headless Chrome if no browser is installed
+  mdrender doctor          check the installation, browser and configuration
 
 Header/footer placeholders: {page} {pages} {title} {author} {date}; "|" separates
 left | center | right columns.
@@ -105,7 +115,11 @@ function cliOverrides(program) {
         if (program.getOptionValueSource(key) === "cli")
             raw[key] = program.getOptionValue(key);
     }
-    return normalizeOptions(raw, "command line", process.cwd(), (key) => key === "pageNumbers" ? "--no-page-numbers" : toFlag(key));
+    return normalizeOptions(raw, "command line", process.cwd(), (key) => key === "pageNumbers"
+        ? "--no-page-numbers"
+        : key === "mermaidAutofit"
+            ? "--no-mermaid-autofit"
+            : toFlag(key));
 }
 function settings(program, options) {
     return {
@@ -143,6 +157,32 @@ async function runSetup(argv, io) {
         return parsed;
     return setup({ io, force: Boolean(program.opts().force) });
 }
+function buildDoctorProgram(io) {
+    const program = new Command()
+        .name("mdrender doctor")
+        .description("Check the installation, browser and configuration, and try a real conversion.\n" +
+        "Exits with 1 when a problem is found.")
+        .option("--browser <path>", "check this browser instead of the detected one")
+        .option("--config <file>", "check this config file (default: nearest mdrender.config.json)")
+        .option("--no-config", "ignore mdrender.config.json files")
+        .option("--quick", "skip starting the browser and the test conversion")
+        .option("--json", "print the report as JSON");
+    return configure(program, io);
+}
+async function runDoctorCommand(argv, io) {
+    const program = buildDoctorProgram(io);
+    const parsed = await parse(program, argv);
+    if (parsed !== undefined)
+        return parsed;
+    const options = program.opts();
+    const report = await runDoctor({
+        browser: options.browser,
+        config: options.config,
+        render: !options.quick,
+    });
+    io.out(options.json ? `${JSON.stringify(report, null, 2)}\n` : formatReport(report));
+    return report.ok ? ExitCode.Ok : ExitCode.Usage;
+}
 async function runPreview(argv, io, signal) {
     const program = buildPreviewProgram(io);
     const parsed = await parse(program, argv);
@@ -192,6 +232,8 @@ export async function main(argv, io = defaultIo, { signal = new AbortController(
             return await runPreview(argv.slice(1), io, signal);
         if (argv[0] === "setup")
             return await runSetup(argv.slice(1), io);
+        if (argv[0] === "doctor")
+            return await runDoctorCommand(argv.slice(1), io);
         return await runRender(argv, io, signal);
     }
     catch (error) {

package/dist/convert.d.ts

@@ -2,6 +2,7 @@ import type { Diagnostic } from "./diagnostics.js";
 import { type DocumentOptions, type Margins, type MermaidTheme } from "./options.js";
 import type { OutputFormat } from "./paths.js";
 import { BrowserSession } from "./render/browser.js";
+import { type DiagramLayout } from "./render/mermaid.js";
 /** Settings shared by every file of a run (batch, watch or preview). */
 export interface RenderSettings {
     /** Explicit browser executable. */
@@ -30,6 +31,8 @@ export interface ConvertResult {
     output: string;
     /** Problems found while rendering; the output is still written, with errors shown inline. */
     diagnostics: Diagnostic[];
+    /** Details for --verbose, such as the layout chosen for each Mermaid flowchart. */
+    notes: Note[];
     /** The effective options after merging config file, front matter and command line. */
     options: DocumentOptions;
     /** Config file that was applied, if any. */
@@ -59,12 +62,20 @@ export declare class BrowserPool {
  */
 export declare const MIN_HEADER_FOOTER_MARGIN = "10mm";
 export declare function headerFooterSpaceWarnings(margin: Margins, hasHeader: boolean, hasFooter: boolean): Diagnostic[];
+export interface Note {
+    line?: number;
+    message: string;
+}
+/** "Mermaid autofit: wrap 300, turned LR→TB, scale 0.33 → 1.00, height 81 → 903 px". */
+export declare function describeLayout(layout: DiagramLayout): string;
 /** Mermaid theme: explicit choice, else dark diagrams for the dark page theme. */
 export declare function effectiveMermaidTheme(options: DocumentOptions): MermaidTheme;
 /**
  * Render a Markdown file to a complete HTML document. A browser is only started (through
  * `browsers`) when the document has Mermaid diagrams.
  */
-export declare function renderDocument(inputPath: string, settings: RenderSettings, browsers: BrowserPool): Promise<RenderedDocument>;
+export declare function renderDocument(inputPath: string, settings: RenderSettings, browsers: BrowserPool, 
+/** Printed on pages (PDF): diagrams are fitted to the page height, not only the width. */
+paged?: boolean): Promise<RenderedDocument>;
 /** Read a Markdown file and write it as a self-contained HTML document or a PDF. */
 export declare function convertFile(convert: ConvertOptions): Promise<ConvertResult>;

package/dist/convert.js

@@ -7,12 +7,13 @@ import { extractFrontMatter } from "./frontmatter.js";
 import { strings } from "./i18n.js";
 import { renderMarkdown } from "./markdown/index.js";
 import { buildToc, tocPlaceholder } from "./markdown/toc.js";
-import { mergeOptions, normalizeOptions, OptionsError, resolveMargins, } from "./options.js";
+import { DEFAULT_FONT_SIZE, fontSizePx, mergeOptions, normalizeOptions, OptionsError, resolveMargins, } from "./options.js";
 import { BrowserSession } from "./render/browser.js";
 import { DEFAULT_FOOTER, headerFooterTemplate } from "./render/header-footer.js";
 import { fillMermaid, renderMermaid } from "./render/mermaid.js";
-import { contentWidthPx, lengthToPx } from "./render/page.js";
-import { buildHtmlDocument, builtinThemeCss } from "./render/template.js";
+import { SMALL_SCALE } from "./render/mermaid-fit.js";
+import { contentHeightPx, contentWidthPx, lengthToPx } from "./render/page.js";
+import { buildHtmlDocument, builtinThemeCss, densityCss } from "./render/template.js";
 import { writeFileAtomic } from "./write.js";
 /** Starts one browser on first use and keeps it for later conversions. */
 export class BrowserPool {
@@ -78,6 +79,27 @@ export function headerFooterSpaceWarnings(margin, hasHeader, hasFooter) {
     }
     return warnings;
 }
+/** Font size, if set, and the page's text height (used to fit images and diagrams). */
+function layoutCss(options, margin) {
+    const height = contentHeightPx(options.pageSize, options.orientation === "landscape", margin);
+    const rules = [`:root { --page-content-height: ${height}px; }`];
+    if (options.fontSize)
+        rules.push(`html { font-size: ${options.fontSize}; }`);
+    return rules.join("\n");
+}
+const fixed2 = (n) => n.toFixed(2);
+/** "Mermaid autofit: wrap 300, turned LR→TB, scale 0.33 → 1.00, height 81 → 903 px". */
+export function describeLayout(layout) {
+    const changes = [
+        layout.wrap === undefined ? undefined : `wrap ${layout.wrap}`,
+        layout.turned ? `turned ${layout.turned}` : undefined,
+    ].filter(Boolean);
+    const scale = `scale ${fixed2(layout.baseScale)} → ${fixed2(layout.scale)}`;
+    const height = `height ${layout.baseHeight} → ${layout.height} px`;
+    return changes.length === 0
+        ? `Mermaid autofit: kept as written (scale ${fixed2(layout.scale)}, ${layout.tried} layouts tried)`
+        : `Mermaid autofit: ${changes.join(", ")}, ${scale}, ${height} (${layout.tried} layouts tried)`;
+}
 /** Mermaid theme: explicit choice, else dark diagrams for the dark page theme. */
 export function effectiveMermaidTheme(options) {
     return options.mermaidTheme ?? (options.theme === "dark" ? "dark" : "neutral");
@@ -86,7 +108,9 @@ export function effectiveMermaidTheme(options) {
  * Render a Markdown file to a complete HTML document. A browser is only started (through
  * `browsers`) when the document has Mermaid diagrams.
  */
-export async function renderDocument(inputPath, settings, browsers) {
+export async function renderDocument(inputPath, settings, browsers, 
+/** Printed on pages (PDF): diagrams are fitted to the page height, not only the width. */
+paged = false) {
     const input = path.resolve(inputPath);
     const baseDir = path.dirname(input);
     const source = await readFile(input, "utf8");
@@ -106,6 +130,7 @@ export async function renderDocument(inputPath, settings, browsers) {
         ...config.warnings.map((message) => ({ severity: "warning", message })),
         ...md.diagnostics,
     ];
+    const notes = [];
     const title = options.title ?? md.title ?? path.parse(input).name;
     // Table of contents: at the [[toc]] marker, or at the start with --toc.
     let body = md.html;
@@ -121,10 +146,37 @@ export async function renderDocument(inputPath, settings, browsers) {
         const session = await browsers.get();
         const width = contentWidthPx(options.pageSize, options.orientation === "landscape", margin);
         const theme = effectiveMermaidTheme(options);
-        const results = await renderMermaid(session, md.mermaid, theme, width);
+        const fontPx = fontSizePx(options.fontSize ?? DEFAULT_FONT_SIZE);
+        const landscape = options.orientation === "landscape";
+        const results = await renderMermaid(session, md.mermaid, {
+            theme,
+            widthPx: width,
+            fontPx,
+            // Same limit as the print stylesheet: the page's text height minus 6 mm.
+            pageHeightPx: paged
+                ? contentHeightPx(options.pageSize, landscape, margin) - lengthToPx("6mm")
+                : Infinity,
+            autofit: options.mermaidAutofit,
+            flip: options.mermaidFlip,
+        });
         const filled = fillMermaid(body, md.nonce, md.mermaid, results);
         body = filled.html;
         diagnostics.push(...filled.diagnostics);
+        md.mermaid.forEach((block, i) => {
+            const result = results[i];
+            if (!result || "error" in result)
+                return;
+            if (result.layout)
+                notes.push({ line: block.line, message: describeLayout(result.layout) });
+            if (paged && result.scale !== undefined && result.scale < SMALL_SCALE) {
+                diagnostics.push({
+                    severity: "warning",
+                    line: block.line,
+                    message: `Mermaid diagram printed at ${Math.round(result.scale * 100)}% of its size; ` +
+                        "split it or shorten its labels to make it readable",
+                });
+            }
+        });
     }
     const html = buildHtmlDocument({
         title,
@@ -136,6 +188,7 @@ export async function renderDocument(inputPath, settings, browsers) {
         date: options.date,
         showTitle: options.title !== undefined,
         themeCss,
+        layoutCss: [...densityCss(options.density), layoutCss(options, margin)],
         extraCss,
     });
     diagnostics.sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
@@ -144,14 +197,14 @@ export async function renderDocument(inputPath, settings, browsers) {
         ...(options.theme.endsWith(".css") ? [options.theme] : []),
         ...options.css,
     ];
-    return { html, title, diagnostics, options, configFile, dependencies };
+    return { html, title, diagnostics, notes, options, configFile, dependencies };
 }
 /** Read a Markdown file and write it as a self-contained HTML document or a PDF. */
 export async function convertFile(convert) {
     const output = path.resolve(convert.output);
     const browsers = convert.browsers ?? new BrowserPool(convert.browser);
     try {
-        const doc = await renderDocument(convert.input, convert, browsers);
+        const doc = await renderDocument(convert.input, convert, browsers, convert.format === "pdf");
         const { options } = doc;
         if (convert.format === "pdf") {
             const margin = resolveMargins(options);
@@ -185,6 +238,7 @@ export async function convertFile(convert) {
         return {
             output,
             diagnostics: doc.diagnostics,
+            notes: doc.notes,
             options,
             configFile: doc.configFile,
             dependencies: doc.dependencies,

package/dist/doctor.d.ts

@@ -0,0 +1,30 @@
+export type CheckStatus = "ok" | "warn" | "fail" | "info";
+export interface Check {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+    /** What to do about a warning or failure. */
+    hint?: string;
+}
+export interface DoctorOptions {
+    /** Explicit browser executable (as with --browser). */
+    browser?: string;
+    /** Config file to check; undefined: nearest to `cwd`; false: none. */
+    config?: string | false;
+    /** Start the browser and convert a sample document (the slow part). Default: true. */
+    render?: boolean;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+}
+export interface DoctorReport {
+    version: string;
+    checks: Check[];
+    ok: boolean;
+}
+/** Where `mdrender` resolves on the PATH, like `which`/`where`. */
+export declare function findOnPath(env: Record<string, string | undefined>, platform?: NodeJS.Platform): string | undefined;
+/** Inspect the installation, browser and configuration, and try a real conversion. */
+export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
+/** Plain-text report; ASCII markers so it reads well in any Windows console. */
+export declare function formatReport(report: DoctorReport): string;