@imontene/mdrender 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Cambios
 
+## 2.3.0 — 2026-10-16
+
+- **Manrope es la nueva tipografía por defecto** del texto, el encabezado, el pie y los
+  diagramas Mermaid. `--font inter` (o `font: inter`) conserva Inter, la de versiones
+  anteriores. Manrope no tiene cursivas (el navegador inclina la normal) y toma de Inter los
+  símbolos que le faltan (`→`, `✓`, `≤`…).
+
+## 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é,

package/README.md

@@ -2,7 +2,7 @@
 
 **Convierte archivos Markdown (`.md`) en PDF y HTML desde la línea de comandos, en Windows y
 Linux**, con ecuaciones LaTeX, diagramas Mermaid y la tipografía
-[Inter](https://fonts.google.com/specimen/Inter).
+[Manrope](https://fonts.google.com/specimen/Manrope) (o [Inter](https://fonts.google.com/specimen/Inter)).
 
 ```bash
 mdrender informe.md            # → informe.pdf
@@ -15,7 +15,8 @@ Ejemplo: [`examples/ejemplo.md`](examples/ejemplo.md) → [`examples/ejemplo.pdf
 - 📄 **Markdown → PDF o HTML autocontenido** (fuentes, imágenes y diagramas incluidos).
 - ➗ **Ecuaciones** `$…$` y `$$…$$` con KaTeX, dibujadas al convertir (sin JavaScript en la salida).
 - 📊 **Diagramas Mermaid**: flujo, secuencia, clases, estados, ER, Gantt, torta, mapa mental…
-- 🔤 **Inter** para el texto y **JetBrains Mono** para el código, incrustadas en el PDF.
+- 🔤 **Manrope** para el texto (o **Inter** con `--font inter`) y **JetBrains Mono** para el
+  código, incrustadas en el PDF.
 - 🧩 **GFM**: tablas, listas de tareas, tachado, notas al pie, alertas `> [!NOTE]`,
   resaltado de código para ~35 lenguajes.
 - 🖨️ Tamaño de página, márgenes, orientación, encabezado/pie con números de página,
@@ -134,37 +135,40 @@ 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                             | —                  |
-| `--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` |
-| `--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                                     | —                  |
+| `--font <manrope\|inter>`      | Tipografía del texto (ver abajo)                                     | `manrope`          |
+| `--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`,
@@ -173,6 +177,13 @@ 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.
 
+**Tipografía**: el texto usa [Manrope](https://fonts.google.com/specimen/Manrope);
+`--font inter` (o `font: inter` en el front matter o en `mdrender.config.json`) vuelve a
+[Inter](https://fonts.google.com/specimen/Inter), la tipografía de las versiones anteriores.
+Ambas van incrustadas en el PDF, también en el encabezado, el pie y los diagramas. Manrope no
+tiene cursivas (el navegador inclina la normal) ni algunos símbolos como `→`, `✓` o `≤`, que
+se toman de Inter.
+
 **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:
@@ -237,6 +248,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]`,
@@ -297,6 +327,6 @@ cambios: [CHANGELOG.md](CHANGELOG.md).
 
 ## Licencia
 
-[MIT](LICENSE). Inter y JetBrains Mono se distribuyen bajo la
+[MIT](LICENSE). Manrope, Inter y JetBrains Mono se distribuyen bajo la
 [SIL Open Font License 1.1](https://openfontlicense.org); los ejecutables incluyen
 `THIRD-PARTY-NOTICES.txt` con las licencias de todos los componentes.

package/dist/assets/theme.css

@@ -1,7 +1,8 @@
-/* mdrender light theme — Inter for text, JetBrains Mono for code. */
+/* mdrender light theme — Manrope (or Inter) for text, JetBrains Mono for code. */
 
 :root {
-  --font-text: "Inter", system-ui, sans-serif;
+  /* mdrender sets both after the theme for the chosen --font (render/fonts.ts). */
+  --font-text: "Manrope", "Inter", system-ui, sans-serif;
   /* Inter after the mono font covers symbols (arrows, math) missing from the code font. */
   --font-code: "JetBrains Mono", "Inter", ui-monospace, monospace;
   --color-text: #1f2328;
@@ -352,6 +353,21 @@ div.math-error {
   .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. */

package/dist/assets.d.ts

@@ -31,6 +31,8 @@ export declare const INTER_FACES: readonly [{
     readonly style: "italic";
     readonly file: "Inter-BoldItalic.woff2";
 }];
+/** Manrope faces in use (Fontsource, split into unicode-range subsets); it has no italics. */
+export declare const MANROPE_STYLESHEETS: string[];
 export declare const MONO_STYLESHEETS: string[];
 export declare const KATEX_CSS = "katex/dist/katex.min.css";
 export declare const MERMAID_JS = "mermaid/dist/mermaid.min.js";

package/dist/assets.js

@@ -78,6 +78,12 @@ export const INTER_FACES = [
     { weight: 700, style: "normal", file: "Inter-Bold.woff2" },
     { weight: 700, style: "italic", file: "Inter-BoldItalic.woff2" },
 ];
+/** Manrope faces in use (Fontsource, split into unicode-range subsets); it has no italics. */
+export const MANROPE_STYLESHEETS = [
+    "@fontsource/manrope/400.css",
+    "@fontsource/manrope/600.css",
+    "@fontsource/manrope/700.css",
+];
 export const MONO_STYLESHEETS = [
     "@fontsource/jetbrains-mono/400.css",
     "@fontsource/jetbrains-mono/400-italic.css",
@@ -103,7 +109,7 @@ export function assetManifest() {
     const keys = new Set([PACKAGE_JSON, ...THEMES, MERMAID_JS]);
     for (const { file } of INTER_FACES)
         keys.add(`${INTER_DIR}/${file}`);
-    for (const cssKey of [...MONO_STYLESHEETS, KATEX_CSS]) {
+    for (const cssKey of [...MANROPE_STYLESHEETS, ...MONO_STYLESHEETS, KATEX_CSS]) {
         keys.add(cssKey);
         for (const font of woff2References(cssKey, readTextAsset(cssKey)))
             keys.add(font);

package/dist/cli.js

@@ -25,11 +25,14 @@ const DOCUMENT_FLAGS = [
     "header",
     "footer",
     "pageNumbers",
+    "font",
     "density",
     "fontSize",
     "css",
     "theme",
     "mermaidTheme",
+    "mermaidAutofit",
+    "mermaidFlip",
     "lang",
     "title",
 ];
@@ -55,11 +58,14 @@ 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("--font <font>", "text typeface: manrope or inter (default: manrope)")
         .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)")
@@ -73,7 +79,7 @@ function configure(command, io) {
 function buildRenderProgram(io) {
     const program = new Command()
         .name("mdrender")
-        .description("Render Markdown files to PDF (or self-contained HTML) using the Inter typeface.")
+        .description("Render Markdown files to PDF (or self-contained HTML) set in Manrope (or Inter).")
         .version(version, "-V, --version")
         .argument("<inputs...>", "Markdown files, folders or glob patterns (e.g. docs/**/*.md)")
         .option("-o, --output <path>", "output file, or folder for several inputs")
@@ -111,7 +117,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 {

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

@@ -11,6 +11,8 @@ import { DEFAULT_FONT_SIZE, fontSizePx, mergeOptions, normalizeOptions, OptionsE
 import { BrowserSession } from "./render/browser.js";
 import { DEFAULT_FOOTER, headerFooterTemplate } from "./render/header-footer.js";
 import { fillMermaid, renderMermaid } from "./render/mermaid.js";
+import { SMALL_SCALE } from "./render/mermaid-fit.js";
+import { FONT_FAMILIES, fontStack } from "./render/fonts.js";
 import { contentHeightPx, contentWidthPx, lengthToPx } from "./render/page.js";
 import { buildHtmlDocument, builtinThemeCss, densityCss } from "./render/template.js";
 import { writeFileAtomic } from "./write.js";
@@ -81,11 +83,33 @@ export function headerFooterSpaceWarnings(margin, hasHeader, hasFooter) {
 /** 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; }`];
+    const family = FONT_FAMILIES[options.font];
+    const rules = [
+        `:root { --page-content-height: ${height}px; }`,
+        `:root { --font-text: ${fontStack(options.font)}; ` +
+            `--font-code: "JetBrains Mono", "${family}", "Inter", ui-monospace, monospace; }`,
+    ];
+    // Manrope's glyphs are taller than the headings' 1.25 line height (about 1.37 em). When a
+    // heading is pushed to the next page, Chrome then repeats its text in the PDF bookmark.
+    if (options.font === "manrope")
+        rules.push("h1, h2, h3, h4, h5, h6 { line-height: 1.4; }");
     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");
@@ -94,7 +118,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");
@@ -114,6 +140,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;
@@ -130,10 +157,37 @@ export async function renderDocument(inputPath, settings, browsers) {
         const width = contentWidthPx(options.pageSize, options.orientation === "landscape", margin);
         const theme = effectiveMermaidTheme(options);
         const fontPx = fontSizePx(options.fontSize ?? DEFAULT_FONT_SIZE);
-        const results = await renderMermaid(session, md.mermaid, theme, width, fontPx);
+        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,
+            font: options.font,
+        });
         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,
@@ -145,6 +199,7 @@ export async function renderDocument(inputPath, settings, browsers) {
         date: options.date,
         showTitle: options.title !== undefined,
         themeCss,
+        font: options.font,
         layoutCss: [...densityCss(options.density), layoutCss(options, margin)],
         extraCss,
     });
@@ -154,14 +209,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);
@@ -175,9 +230,11 @@ export async function convertFile(convert) {
                 landscape: options.orientation === "landscape",
                 margin,
                 headerTemplate: hasHeaderFooter
-                    ? headerFooterTemplate(options.header, values, margin)
+                    ? headerFooterTemplate(options.header, values, margin, options.font)
+                    : undefined,
+                footerTemplate: hasHeaderFooter
+                    ? headerFooterTemplate(footer, values, margin, options.font)
                     : undefined,
-                footerTemplate: hasHeaderFooter ? headerFooterTemplate(footer, values, margin) : undefined,
                 allowRemote: convert.allowRemote,
             });
             for (const url of blocked) {
@@ -195,6 +252,7 @@ export async function convertFile(convert) {
         return {
             output,
             diagnostics: doc.diagnostics,
+            notes: doc.notes,
             options,
             configFile: doc.configFile,
             dependencies: doc.dependencies,

package/dist/doctor.js

@@ -135,8 +135,9 @@ function settingsCheck(options) {
         name: "Settings",
         status: "info",
         detail: `${options.pageSize} ${options.orientation}, margins ${m.top} ${m.right} ${m.bottom} ` +
-            `${m.left} (top right bottom left), ${options.density} density, ` +
-            `${options.fontSize ?? DEFAULT_FONT_SIZE} text, language ${options.lang}, theme ` +
+            `${m.left} (top right bottom left), ${options.font} ` +
+            `${options.fontSize ?? DEFAULT_FONT_SIZE}, ${options.density} density, ` +
+            `language ${options.lang}, theme ` +
             path.basename(options.theme),
     };
 }

package/dist/markdown/env.d.ts

@@ -4,6 +4,8 @@ export interface MermaidBlock {
     source: string;
     /** 1-based source line of the opening fence. */
     line?: number;
+    /** Printed together with the heading just above it (see markdown/keep-with-heading.ts). */
+    afterHeading?: boolean;
 }
 /** Per-document state shared by the Markdown plugins during one render. */
 export interface RenderEnv extends Env {

package/dist/markdown/index.js

@@ -8,6 +8,7 @@ import { codeBlocks } from "./code-blocks.js";
 import { inlineChildLines } from "./env.js";
 import { highlightCode } from "./highlight.js";
 import { inlineLocalImages } from "./images.js";
+import { keepWithHeading } from "./keep-with-heading.js";
 import { math } from "./math.js";
 import { mermaid } from "./mermaid.js";
 import { taskLists } from "./task-lists.js";
@@ -24,6 +25,7 @@ export function createMarkdown() {
     md.use(taskLists);
     md.use(alerts);
     md.use(tocMarker);
+    md.use(keepWithHeading);
     md.use(inlineChildLines);
     md.use(inlineLocalImages);
     // Before math and mermaid, which hand their non-code fences on to this renderer.

package/dist/markdown/keep-with-heading.d.ts

@@ -0,0 +1,8 @@
+import type { MarkdownIt } from "markdown-it";
+export declare const KEEP_WITH_HEADING_CLASS = "keep-with-heading";
+/**
+ * Wrap a top-level heading and the diagram or lone image right after it in a block that is not
+ * split across pages (`.keep-with-heading` in theme.css). Otherwise a figure that does not fit at
+ * the bottom of a page moves to the next one and leaves its heading alone at the bottom.
+ */
+export declare function keepWithHeading(md: MarkdownIt): void;

package/dist/markdown/keep-with-heading.js

@@ -0,0 +1,44 @@
+export const KEEP_WITH_HEADING_CLASS = "keep-with-heading";
+const isMermaidFence = (token) => token?.type === "fence" && token.info.trim().toLowerCase() === "mermaid";
+/** A paragraph holding nothing but one image (`![alt](img.png)`). */
+function imageParagraphEnd(tokens, i) {
+    if (tokens[i]?.type !== "paragraph_open" || tokens[i + 2]?.type !== "paragraph_close") {
+        return undefined;
+    }
+    const children = tokens[i + 1]?.children?.filter((child) => !(child.type === "text" && child.content.trim() === ""));
+    return children?.length === 1 && children[0].type === "image" ? i + 2 : undefined;
+}
+/**
+ * Wrap a top-level heading and the diagram or lone image right after it in a block that is not
+ * split across pages (`.keep-with-heading` in theme.css). Otherwise a figure that does not fit at
+ * the bottom of a page moves to the next one and leaves its heading alone at the bottom.
+ */
+export function keepWithHeading(md) {
+    md.core.ruler.push("keep_with_heading", (state) => {
+        const tokens = state.tokens;
+        for (let i = 0; i < tokens.length; i++) {
+            const open = tokens[i];
+            if (open.type !== "heading_open" || open.level !== 0)
+                continue;
+            const next = i + 3; // heading_open, inline, heading_close
+            let end;
+            if (isMermaidFence(tokens[next])) {
+                end = next;
+                tokens[next].meta = { ...tokens[next].meta, afterHeading: true };
+            }
+            else {
+                end = imageParagraphEnd(tokens, next);
+            }
+            if (end === undefined)
+                continue;
+            const before = new state.Token("html_block", "", 0);
+            before.content = `<div class="${KEEP_WITH_HEADING_CLASS}">\n`;
+            const after = new state.Token("html_block", "", 0);
+            after.content = "</div>\n";
+            tokens.splice(end + 1, 0, after);
+            tokens.splice(i, 0, before);
+            i = end + 2;
+        }
+    });
+}
+//# sourceMappingURL=keep-with-heading.js.map

package/dist/markdown/mermaid.js

@@ -15,7 +15,9 @@ export function mermaid(md) {
             return fence(tokens, idx, options, rawEnv, self);
         }
         const env = rawEnv;
-        const index = env.mermaid.push({ source: token.content, line: tokenLine(token) }) - 1;
+        const block = { source: token.content, line: tokenLine(token) };
+        const afterHeading = token.meta?.afterHeading;
+        const index = env.mermaid.push(afterHeading ? { ...block, afterHeading } : block) - 1;
         return `<figure class="mermaid-diagram">${mermaidPlaceholder(env.nonce, index)}</figure>\n`;
     };
 }

package/dist/options.d.ts

@@ -11,7 +11,11 @@ export type Margins = {
 };
 export declare const MERMAID_THEMES: readonly ["default", "neutral", "dark", "forest", "base"];
 export type MermaidTheme = (typeof MERMAID_THEMES)[number];
+export declare const MERMAID_FLIPS: readonly ["auto", "never"];
+export type MermaidFlip = (typeof MERMAID_FLIPS)[number];
 export declare const BUILTIN_THEMES: readonly ["light", "dark"];
+export declare const TEXT_FONTS: readonly ["manrope", "inter"];
+export type TextFont = (typeof TEXT_FONTS)[number];
 export declare const DENSITIES: readonly ["normal", "compact"];
 export type Density = (typeof DENSITIES)[number];
 /** Rendering options, merged from defaults < config file < front matter < command line. */
@@ -35,6 +39,12 @@ export interface DocumentOptions {
     footer?: string;
     /** Mermaid theme; when unset, "neutral" for light pages and "dark" for the dark theme. */
     mermaidTheme?: MermaidTheme;
+    /** Try several layouts of each flowchart and keep the one whose text prints largest. */
+    mermaidAutofit: boolean;
+    /** Whether autofit may turn a flowchart to the other axis (LR ↔ TB) when it reads far better. */
+    mermaidFlip: MermaidFlip;
+    /** Typeface of the text: Manrope or Inter (code is always JetBrains Mono). */
+    font: TextFont;
     /** Vertical spacing: "compact" tightens line height, paragraph and heading spacing. */
     density: Density;
     /** Base font size of the text, e.g. "10pt"; when unset, the theme's (10.5pt). */