@imontene/mdrender 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Cambios
 
+## 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,37 @@ 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` |
+| `--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 +173,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 +213,8 @@ header: "{title} | | {date}"
   "pageSize": "Letter",
   "margin": "15mm",
   "marginLeft": "25mm",
+  "density": "compact",
+  "fontSize": "10pt",
   "css": "estilos/empresa.css"
 }
 ```

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,17 @@ 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);
+  }
+}
+
 /* 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,6 +25,8 @@ const DOCUMENT_FLAGS = [
     "header",
     "footer",
     "pageNumbers",
+    "density",
+    "fontSize",
     "css",
     "theme",
     "mermaidTheme",
@@ -52,6 +55,8 @@ 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)`)
@@ -80,6 +85,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.
@@ -143,6 +149,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 +224,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.js

@@ -7,12 +7,12 @@ 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 { 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 +78,14 @@ 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");
+}
 /** Mermaid theme: explicit choice, else dark diagrams for the dark page theme. */
 export function effectiveMermaidTheme(options) {
     return options.mermaidTheme ?? (options.theme === "dark" ? "dark" : "neutral");
@@ -121,7 +129,8 @@ 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 results = await renderMermaid(session, md.mermaid, theme, width, fontPx);
         const filled = fillMermaid(body, md.nonce, md.mermaid, results);
         body = filled.html;
         diagnostics.push(...filled.diagnostics);
@@ -136,6 +145,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));

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;

package/dist/doctor.js

@@ -0,0 +1,278 @@
+import { existsSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import sea from "node:sea";
+import { assetPath, PACKAGE_JSON } from "./assets.js";
+import { cacheDir, installedBrowser } from "./browser/cache.js";
+import { findBrowser } from "./browser/detect.js";
+import { findConfigFile, readConfig } from "./config.js";
+import { BrowserPool, convertFile } from "./convert.js";
+import { DEFAULT_FONT_SIZE, mergeOptions, resolveMargins } from "./options.js";
+import { version } from "./version.js";
+const MIN_NODE = [22, 12];
+function runningAsExecutable() {
+    try {
+        return sea.isSea();
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Where `mdrender` resolves on the PATH, like `which`/`where`. */
+export function findOnPath(env, platform = process.platform) {
+    const pathValue = Object.entries(env).find(([key]) => key.toUpperCase() === "PATH")?.[1] ?? "";
+    const separator = platform === "win32" ? ";" : ":";
+    const names = platform === "win32"
+        ? ["mdrender.exe", "mdrender.cmd", "mdrender.ps1", "mdrender"]
+        : ["mdrender"];
+    const join = platform === "win32" ? path.win32.join : path.posix.join;
+    for (const dir of pathValue.split(separator).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = join(dir, name);
+            if (isFile(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function installationChecks(env, platform) {
+    const checks = [];
+    const executable = runningAsExecutable();
+    checks.push({
+        name: "mdrender",
+        status: "ok",
+        detail: executable
+            ? `${version}, standalone executable (${process.execPath})`
+            : `${version}, npm package (${path.dirname(assetPath(PACKAGE_JSON))})`,
+    });
+    if (!executable) {
+        const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+        const [needMajor, needMinor] = MIN_NODE;
+        const supported = major > needMajor || (major === needMajor && minor >= needMinor);
+        checks.push({
+            name: "Node.js",
+            status: supported ? "ok" : "fail",
+            detail: `${process.versions.node} (${process.execPath})`,
+            hint: supported ? undefined : `mdrender needs Node.js ${needMajor}.${needMinor} or newer`,
+        });
+    }
+    checks.push({
+        name: "System",
+        status: "info",
+        detail: `${platform} ${process.arch}, ${os.release()}`,
+    });
+    const onPath = findOnPath(env, platform);
+    checks.push(onPath
+        ? { name: "PATH", status: "ok", detail: `mdrender found at ${onPath}` }
+        : {
+            name: "PATH",
+            status: "warn",
+            detail: "the mdrender command is not in any PATH folder",
+            hint: "you can only run it by its full path or with npx; add its folder to PATH " +
+                "(for npm: the output of `npm prefix -g`, plus /bin on Linux)",
+        });
+    return checks;
+}
+function browserSource(found, explicit, env, downloaded) {
+    if (explicit)
+        return "from --browser";
+    if (env.MDRENDER_BROWSER)
+        return "from MDRENDER_BROWSER";
+    if (downloaded && path.resolve(found) === path.resolve(downloaded)) {
+        return "downloaded by mdrender setup";
+    }
+    return "installed on this system";
+}
+function configChecks(options, cwd) {
+    if (options.config === false) {
+        return [{ name: "Config", status: "info", detail: "config files disabled (--no-config)" }];
+    }
+    const file = options.config ? path.resolve(cwd, options.config) : findConfigFile(cwd);
+    if (!file) {
+        const defaults = mergeOptions();
+        return [
+            {
+                name: "Config",
+                status: "info",
+                detail: `no mdrender.config.json in ${cwd} or its parent folders; defaults apply`,
+            },
+            settingsCheck(defaults),
+        ];
+    }
+    if (!existsSync(file)) {
+        return [{ name: "Config", status: "fail", detail: `not found: ${file}` }];
+    }
+    try {
+        const config = readConfig(file);
+        const checks = [
+            config.warnings.length
+                ? {
+                    name: "Config",
+                    status: "warn",
+                    detail: `${file}\n${config.warnings.map((w) => `  - ${w}`).join("\n")}`,
+                    hint: "fix or remove the options above; they are ignored",
+                }
+                : { name: "Config", status: "ok", detail: file },
+        ];
+        checks.push(settingsCheck(mergeOptions(config.options)));
+        return checks;
+    }
+    catch (error) {
+        return [{ name: "Config", status: "fail", detail: error.message }];
+    }
+}
+function settingsCheck(options) {
+    const m = resolveMargins(options);
+    return {
+        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 ` +
+            path.basename(options.theme),
+    };
+}
+const SAMPLE = `# mdrender doctor
+
+Equation: $e^{i\\pi} + 1 = 0$
+
+\`\`\`mermaid
+flowchart LR
+  A[Markdown] --> B[PDF]
+\`\`\`
+`;
+async function browserChecks(options, env, platform) {
+    const checks = [];
+    const dir = cacheDir(env, platform);
+    const downloaded = installedBrowser(dir);
+    checks.push({
+        name: "Setup cache",
+        status: "info",
+        detail: downloaded ? `${dir} (contains ${downloaded})` : `${dir} (no downloaded browser)`,
+    });
+    let executable;
+    try {
+        executable = findBrowser(options.browser, {
+            env,
+            platform,
+            downloaded: () => downloaded,
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "Browser",
+            status: "fail",
+            detail: error.message.split("\n")[0],
+            hint: "run `mdrender setup` to download one, install Chrome/Edge/Chromium, or point to " +
+                "one with --browser <path> or MDRENDER_BROWSER",
+        });
+        return checks;
+    }
+    checks.push({
+        name: "Browser",
+        status: "ok",
+        detail: `${executable} (${browserSource(executable, options.browser, env, downloaded)})`,
+    });
+    if (options.render === false)
+        return checks;
+    const notes = [];
+    const pool = new BrowserPool(executable, (message) => notes.push(message));
+    const work = mkdtempSync(path.join(os.tmpdir(), "mdrender-doctor-"));
+    try {
+        let started = Date.now();
+        const session = await pool.get();
+        const browserVersion = await session.version();
+        const unsandboxed = notes.some((note) => note.includes("sandbox"));
+        checks.push({
+            name: "Browser start",
+            status: unsandboxed ? "warn" : "ok",
+            detail: `${browserVersion} in ${Date.now() - started} ms`,
+            hint: unsandboxed
+                ? "started without Chrome's sandbox (blocked by the system, e.g. Ubuntu 23.10+); " +
+                    "conversions still work. A browser installed from a package avoids it"
+                : undefined,
+        });
+        const input = path.join(work, "doctor.md");
+        writeFileSync(input, SAMPLE);
+        started = Date.now();
+        const result = await convertFile({
+            input,
+            output: path.join(work, "doctor.pdf"),
+            format: "pdf",
+            config: false,
+            browsers: pool,
+        });
+        const problems = result.diagnostics.map((d) => d.message);
+        checks.push({
+            name: "Test conversion",
+            status: problems.length ? "fail" : "ok",
+            detail: problems.length
+                ? problems.join("; ")
+                : `PDF with an equation and a Mermaid diagram in ${Date.now() - started} ms`,
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "Browser start",
+            status: "fail",
+            detail: error.message.split("\n")[0],
+            hint: "try another browser with --browser <path>, or `mdrender setup --force`",
+        });
+    }
+    finally {
+        await pool.close();
+        rmSync(work, { recursive: true, force: true });
+    }
+    return checks;
+}
+function networkChecks(env) {
+    const proxy = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"].find((k) => env[k]);
+    return proxy
+        ? [{ name: "Proxy", status: "info", detail: `${proxy} is set (used by mdrender setup)` }]
+        : [];
+}
+/** Inspect the installation, browser and configuration, and try a real conversion. */
+export async function runDoctor(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const cwd = options.cwd ?? process.cwd();
+    const checks = [
+        ...installationChecks(env, platform),
+        ...(await browserChecks(options, env, platform)),
+        ...configChecks(options, cwd),
+        ...networkChecks(env),
+    ];
+    return { version, checks, ok: !checks.some((check) => check.status === "fail") };
+}
+const LABEL = {
+    ok: "[ok]  ",
+    warn: "[warn]",
+    fail: "[fail]",
+    info: "[info]",
+};
+/** Plain-text report; ASCII markers so it reads well in any Windows console. */
+export function formatReport(report) {
+    const width = Math.max(...report.checks.map((check) => check.name.length));
+    const lines = report.checks.map((check) => {
+        const [first, ...rest] = check.detail.split("\n");
+        const head = `${LABEL[check.status]} ${check.name.padEnd(width)}  ${first}`;
+        const more = rest.map((line) => `${" ".repeat(width + 9)}${line}`);
+        const hint = check.hint ? [`${" ".repeat(width + 9)}-> ${check.hint}`] : [];
+        return [head, ...more, ...hint].join("\n");
+    });
+    const failures = report.checks.filter((c) => c.status === "fail").length;
+    const warnings = report.checks.filter((c) => c.status === "warn").length;
+    const summary = report.ok
+        ? `All good${warnings ? ` (${warnings} warning${warnings > 1 ? "s" : ""})` : ""}.`
+        : `${failures} problem${failures > 1 ? "s" : ""} found.`;
+    return `mdrender doctor\n\n${lines.join("\n")}\n\n${summary}\n`;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/markdown/code-blocks.d.ts

@@ -0,0 +1,9 @@
+import type { MarkdownIt } from "markdown-it";
+/**
+ * Code blocks up to this many lines are kept on one page; longer ones may break across pages
+ * (the theme keeps at least a few lines on each side), so a long listing does not push itself
+ * to the next page and leave a large gap behind.
+ */
+export declare const SHORT_CODE_LINES = 12;
+/** Mark short fenced and indented code blocks with `keep-together` (see SHORT_CODE_LINES). */
+export declare function codeBlocks(md: MarkdownIt): void;

package/dist/markdown/code-blocks.js

@@ -0,0 +1,21 @@
+/**
+ * Code blocks up to this many lines are kept on one page; longer ones may break across pages
+ * (the theme keeps at least a few lines on each side), so a long listing does not push itself
+ * to the next page and leave a large gap behind.
+ */
+export const SHORT_CODE_LINES = 12;
+const KEEP_CLASS = "keep-together";
+function markShort(html, content) {
+    const lines = content.replace(/\n$/, "").split("\n").length;
+    if (lines > SHORT_CODE_LINES || !html.startsWith("<pre"))
+        return html;
+    return html.replace(/^<pre(?: class="([^"]*)")?/, (_m, classes) => classes ? `<pre class="${classes} ${KEEP_CLASS}"` : `<pre class="${KEEP_CLASS}"`);
+}
+/** Mark short fenced and indented code blocks with `keep-together` (see SHORT_CODE_LINES). */
+export function codeBlocks(md) {
+    for (const rule of ["fence", "code_block"]) {
+        const render = md.renderer.rules[rule];
+        md.renderer.rules[rule] = (tokens, idx, options, env, self) => markShort(render(tokens, idx, options, env, self), tokens[idx].content);
+    }
+}
+//# sourceMappingURL=code-blocks.js.map

package/dist/markdown/index.js

@@ -4,6 +4,7 @@ import anchor from "markdown-it-anchor";
 import footnote from "markdown-it-footnote";
 import { DEFAULT_LANG } from "../i18n.js";
 import { alerts } from "./alerts.js";
+import { codeBlocks } from "./code-blocks.js";
 import { inlineChildLines } from "./env.js";
 import { highlightCode } from "./highlight.js";
 import { inlineLocalImages } from "./images.js";
@@ -25,6 +26,8 @@ export function createMarkdown() {
     md.use(tocMarker);
     md.use(inlineChildLines);
     md.use(inlineLocalImages);
+    // Before math and mermaid, which hand their non-code fences on to this renderer.
+    md.use(codeBlocks);
     md.use(math);
     md.use(mermaid);
     return md;

package/dist/options.d.ts

@@ -12,6 +12,8 @@ export type Margins = {
 export declare const MERMAID_THEMES: readonly ["default", "neutral", "dark", "forest", "base"];
 export type MermaidTheme = (typeof MERMAID_THEMES)[number];
 export declare const BUILTIN_THEMES: readonly ["light", "dark"];
+export declare const DENSITIES: readonly ["normal", "compact"];
+export type Density = (typeof DENSITIES)[number];
 /** Rendering options, merged from defaults < config file < front matter < command line. */
 export interface DocumentOptions {
     pageSize: PageSize;
@@ -33,6 +35,10 @@ export interface DocumentOptions {
     footer?: string;
     /** Mermaid theme; when unset, "neutral" for light pages and "dark" for the dark theme. */
     mermaidTheme?: MermaidTheme;
+    /** 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). */
+    fontSize?: string;
     /** "light", "dark", or the absolute path of a stylesheet that replaces the built-in theme. */
     theme: string;
     /** Extra stylesheets (absolute paths), applied after the built-in theme. */
@@ -50,6 +56,10 @@ export declare class OptionsError extends MdRenderError {
 }
 /** Parse a CSS margin shorthand into the four sides, or throw. */
 export declare function parseMargin(margin: string): Margins;
+/** Text size of the built-in themes (theme.css), when --font-size is not given. */
+export declare const DEFAULT_FONT_SIZE = "10.5pt";
+/** A font size in CSS pixels ("10.5pt" → 14). */
+export declare function fontSizePx(size: string): number;
 /**
  * Validate options from a config file, front matter or the command line.
  *

package/dist/options.js

@@ -6,6 +6,7 @@ export const PAGE_SIZES = ["A3", "A4", "A5", "Letter", "Legal", "Tabloid"];
 export const ORIENTATIONS = ["portrait", "landscape"];
 export const MERMAID_THEMES = ["default", "neutral", "dark", "forest", "base"];
 export const BUILTIN_THEMES = ["light", "dark"];
+export const DENSITIES = ["normal", "compact"];
 export const DEFAULT_OPTIONS = {
     pageSize: "Letter",
     margin: "10mm",
@@ -13,6 +14,7 @@ export const DEFAULT_OPTIONS = {
     toc: false,
     tocDepth: 3,
     pageNumbers: true,
+    density: "normal",
     theme: "light",
     css: [],
     lang: DEFAULT_LANG,
@@ -59,6 +61,27 @@ const length = (value, describe) => {
         return trimmed;
     throw new OptionsError(`${describe} must be a length in mm, cm, in or px, e.g. "10mm"`);
 };
+/** Text size of the built-in themes (theme.css), when --font-size is not given. */
+export const DEFAULT_FONT_SIZE = "10.5pt";
+/** Font sizes accepted by --font-size, in points or pixels. */
+const FONT_SIZE = /^(\d+(?:\.\d+)?)(pt|px)$/;
+const FONT_SIZE_PT = { min: 6, max: 24 };
+/** A font size in CSS pixels ("10.5pt" → 14). */
+export function fontSizePx(size) {
+    const match = FONT_SIZE.exec(size);
+    if (!match)
+        throw new Error(`invalid font size: ${size}`);
+    return match[2] === "pt" ? (Number(match[1]) * 4) / 3 : Number(match[1]);
+}
+const fontSize = (value, describe) => {
+    const size = text(value, describe, "").trim();
+    if (FONT_SIZE.test(size)) {
+        const pt = (fontSizePx(size) * 3) / 4;
+        if (pt >= FONT_SIZE_PT.min && pt <= FONT_SIZE_PT.max)
+            return size;
+    }
+    throw new OptionsError(`${describe} must be a size in pt or px from ${FONT_SIZE_PT.min}pt to ${FONT_SIZE_PT.max}pt, e.g. "10pt"`);
+};
 const VALIDATORS = {
     pageSize: oneOf(PAGE_SIZES),
     margin: (value, describe) => {
@@ -87,6 +110,8 @@ const VALIDATORS = {
     header: text,
     footer: text,
     mermaidTheme: oneOf(MERMAID_THEMES),
+    density: oneOf(DENSITIES),
+    fontSize,
     theme: (value, describe, baseDir) => {
         const theme = text(value, describe, baseDir);
         const builtin = BUILTIN_THEMES.find((t) => t === theme.toLowerCase());

package/dist/render/browser.d.ts

@@ -45,5 +45,7 @@ export declare class BrowserSession {
         pdf: Uint8Array;
         blocked: string[];
     }>;
+    /** Browser name and version, e.g. "HeadlessChrome/141.0.7390.37". */
+    version(): Promise<string>;
     close(): Promise<void>;
 }

package/dist/render/browser.js

@@ -127,6 +127,10 @@ export class BrowserSession {
             await page.close();
         }
     }
+    /** Browser name and version, e.g. "HeadlessChrome/141.0.7390.37". */
+    version() {
+        return this.browser.version();
+    }
     async close() {
         await this.browser.close();
     }

package/dist/render/mermaid.d.ts

@@ -14,7 +14,9 @@ type DiagramResult = {
  */
 export declare function renderMermaid(session: BrowserSession, blocks: MermaidBlock[], theme?: MermaidTheme, 
 /** Width of the text column, so diagrams are laid out at their printed size. */
-widthPx?: number): Promise<DiagramResult[]>;
+widthPx?: number, 
+/** Text size of the document in CSS pixels, so diagram labels match the body text. */
+fontPx?: number): Promise<DiagramResult[]>;
 /**
  * Replace the Mermaid placeholders in `html` with rendered SVGs, or with a visible error box.
  * Returns the new HTML and one error diagnostic per failed diagram.

package/dist/render/mermaid.js

@@ -5,6 +5,8 @@ import { escapeHtml } from "../html.js";
 export { MERMAID_THEMES } from "../options.js";
 /** Width of the text column on A4 with 20 mm margins. */
 const DEFAULT_WIDTH_PX = 642;
+/** 10.5pt, the built-in themes' text size (Mermaid's own default is 16px). */
+const DEFAULT_FONT_PX = 14;
 let mermaidJs;
 /**
  * Render Mermaid diagrams to SVG in a blank page that holds no user content: only the diagram
@@ -12,7 +14,9 @@ let mermaidJs;
  */
 export async function renderMermaid(session, blocks, theme = "neutral", 
 /** Width of the text column, so diagrams are laid out at their printed size. */
-widthPx = DEFAULT_WIDTH_PX) {
+widthPx = DEFAULT_WIDTH_PX, 
+/** Text size of the document in CSS pixels, so diagram labels match the body text. */
+fontPx = DEFAULT_FONT_PX) {
     mermaidJs ??= readTextAsset(MERMAID_JS);
     const page = await session.newPage();
     try {
@@ -20,7 +24,7 @@ widthPx = DEFAULT_WIDTH_PX) {
 body { margin: 0; width: ${widthPx}px; font-family: "Inter", sans-serif; }</style>
 </head><body></body></html>`);
         await page.evaluate(mermaidJs);
-        return await page.evaluate(async (sources, theme) => {
+        return await page.evaluate(async (sources, theme, fontPx) => {
             // Runs in the browser. The project is compiled without DOM types, hence PageGlobals.
             const { document, mermaid } = globalThis;
             // Load the font weights Mermaid uses before it measures any text.
@@ -30,8 +34,12 @@ body { margin: 0; width: ${widthPx}px; font-family: "Inter", sans-serif; }</styl
                 securityLevel: "strict",
                 theme,
                 fontFamily: "Inter, sans-serif",
-                themeVariables: { fontFamily: "Inter, sans-serif" },
+                // Sequence diagrams take their text sizes from here, the others from themeVariables.
+                fontSize: fontPx,
+                themeVariables: { fontFamily: "Inter, sans-serif", fontSize: `${fontPx}px` },
                 htmlLabels: true,
+                // Actors only at the top of sequence diagrams: repeating them below costs height.
+                sequence: { mirrorActors: false },
             });
             const results = [];
             for (const [i, source] of sources.entries()) {
@@ -44,7 +52,7 @@ body { margin: 0; width: ${widthPx}px; font-family: "Inter", sans-serif; }</styl
                 }
             }
             return results;
-        }, blocks.map((b) => b.source), theme);
+        }, blocks.map((b) => b.source), theme, fontPx);
     }
     finally {
         await page.close();

package/dist/render/page.d.ts

@@ -5,3 +5,8 @@ export declare function contentWidthPx(pageSize: PageSize, landscape: boolean, m
     left: string;
     right: string;
 }): number;
+/** Height of the text area in CSS pixels: the paper minus the top and bottom margins. */
+export declare function contentHeightPx(pageSize: PageSize, landscape: boolean, margin: {
+    top: string;
+    bottom: string;
+}): number;

package/dist/render/page.js

@@ -20,4 +20,10 @@ export function contentWidthPx(pageSize, landscape, margin) {
     const paperPx = ((landscape ? height : width) * 96) / 25.4;
     return Math.round(paperPx - lengthToPx(margin.left) - lengthToPx(margin.right));
 }
+/** Height of the text area in CSS pixels: the paper minus the top and bottom margins. */
+export function contentHeightPx(pageSize, landscape, margin) {
+    const [width, height] = PAPER_MM[pageSize];
+    const paperPx = ((landscape ? width : height) * 96) / 25.4;
+    return Math.round(paperPx - lengthToPx(margin.top) - lengthToPx(margin.bottom));
+}
 //# sourceMappingURL=page.js.map

package/dist/render/template.d.ts

@@ -2,6 +2,8 @@ import { escapeHtml } from "../html.js";
 export { escapeHtml };
 /** Stylesheets of a built-in theme ("light" or "dark"). */
 export declare function builtinThemeCss(theme: "light" | "dark"): string[];
+/** Stylesheet for a density other than "normal", applied after the theme. */
+export declare function densityCss(density: "normal" | "compact"): string[];
 export interface DocumentParts {
     title: string;
     body: string;
@@ -15,7 +17,9 @@ export interface DocumentParts {
     showTitle?: boolean;
     /** Theme stylesheet contents. Defaults to the built-in light theme. */
     themeCss?: string[];
-    /** Extra stylesheet contents, applied after the theme. */
+    /** Layout stylesheets (density, font size, page height), applied after the theme. */
+    layoutCss?: string[];
+    /** Extra stylesheet contents, applied after the theme and layout. */
     extraCss?: string[];
 }
 /** Wrap a rendered Markdown fragment in a complete, self-contained HTML document. */

package/dist/render/template.js

@@ -17,6 +17,10 @@ function asset(name) {
 export function builtinThemeCss(theme) {
     return theme === "dark" ? [asset("theme.css"), asset("theme-dark.css")] : [asset("theme.css")];
 }
+/** Stylesheet for a density other than "normal", applied after the theme. */
+export function densityCss(density) {
+    return density === "compact" ? [asset("density-compact.css")] : [];
+}
 function titleBlock({ title, subtitle, author, date }) {
     const meta = [author, date].filter(Boolean).map((part) => escapeHtml(part));
     return [
@@ -31,9 +35,15 @@ function titleBlock({ title, subtitle, author, date }) {
 }
 /** Wrap a rendered Markdown fragment in a complete, self-contained HTML document. */
 export function buildHtmlDocument(parts) {
-    const { title, body, math = false, lang, author, extraCss = [] } = parts;
+    const { title, body, math = false, lang, author, layoutCss = [], extraCss = [] } = parts;
     const themeCss = parts.themeCss ?? builtinThemeCss("light");
-    const styles = [fontFaceCss(), ...(math ? [katexCss()] : []), ...themeCss, ...extraCss];
+    const styles = [
+        fontFaceCss(),
+        ...(math ? [katexCss()] : []),
+        ...themeCss,
+        ...layoutCss,
+        ...extraCss,
+    ];
     return `<!doctype html>
 <html${lang ? ` lang="${escapeHtml(lang)}"` : ""}>
 <head>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imontene/mdrender",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Command-line app for Windows and Linux that renders Markdown — with LaTeX equations and Mermaid diagrams — to PDF and HTML using the Inter typeface",
   "keywords": [
     "markdown",