@imontene/mdrender 1.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # 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`
+  (también `marginTop`… en front matter y `mdrender.config.json`), por encima de `--margin`.
+- Orientación con `--orientation portrait|landscape` (`--landscape` sigue funcionando).
+- **Cambian los valores por defecto**: hoja **Letter** (antes A4) y márgenes de **10 mm**
+  (antes 20 mm). Para el formato anterior: `--page-size A4 --margin 20mm`, o ponerlo en
+  `mdrender.config.json`.
+- El proceso de publicación falla al inicio, con un error claro, si falta `NPM_TOKEN`.
+- Nunca sobrescribe el `.md` de entrada: `mdrender doc.md -o doc.md` termina con un error.
+- Avisa de opciones desconocidas en `mdrender.config.json` y sugiere la correcta
+  (`"margn"` → `"margin"`).
+- Escritura segura: el PDF/HTML se escribe en un archivo temporal y se renombra al final; un
+  fallo no deja archivos a medias y conserva la versión anterior. Mensaje claro si el archivo
+  está abierto en otro programa.
+- Avisa si un encabezado o pie no cabe (margen superior o inferior menor de 10 mm).
+
 ## 1.0.1 — 2026-10-12
 
 - Corrige un error EPIPE sin capturar cuando la salida se corta con una tubería

package/README.md

@@ -73,7 +73,7 @@ npm link        # deja disponible el comando `mdrender`
 mdrender documento.md
 
 # Elegir salida, tamaño de página y tabla de contenidos
-mdrender documento.md -o salida/informe.pdf --page-size Letter --toc
+mdrender documento.md -o salida/informe.pdf --page-size A4 --toc
 
 # HTML autocontenido
 mdrender documento.md --format html
@@ -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,30 +134,54 @@ 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>`       | `A3`, `A4`, `A5`, `Letter`, `Legal`, `Tabloid`              | `A4`               |
-| `--margin <valor>`           | Márgenes como en CSS: `20mm`, `15mm 20mm`, `1in 0.75in`…    | `20mm`             |
-| `--landscape`                | Orientación horizontal                                      | —                  |
-| `--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`,
+`--margin-right`, `--margin-bottom` y `--margin-left` ajustan una sola, por encima de
+`--margin`. Ejemplo: `--page-size A4 --orientation landscape --margin 15mm --margin-left 25mm`.
+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:
@@ -151,7 +200,9 @@ subtitle: Resultados del trimestre
 author: Ana Pérez
 date: 2026-10-04
 toc: true
-page-size: Letter
+page-size: A4
+orientation: landscape
+margin-left: 25mm
 header: "{title} | | {date}"
 ---
 ```
@@ -159,8 +210,11 @@ header: "{title} | | {date}"
 ```json
 {
   "lang": "es",
-  "pageSize": "A4",
-  "margin": "25mm 20mm",
+  "pageSize": "Letter",
+  "margin": "15mm",
+  "marginLeft": "25mm",
+  "density": "compact",
+  "fontSize": "10pt",
   "css": "estilos/empresa.css"
 }
 ```
@@ -199,6 +253,10 @@ fecha). Las rutas de `css` y `theme` son relativas al archivo donde aparecen.
   como imágenes referenciadas desde el `.md`.
 - Mermaid corre en una página aparte, sin contenido del usuario, con `securityLevel: "strict"`.
 - La vista previa solo escucha en `127.0.0.1`.
+- Nunca sobrescribe un `.md` de entrada, y escribe cada PDF/HTML en un archivo temporal que
+  renombra al final: si algo falla, el archivo anterior queda intacto.
+- Las opciones mal escritas en `mdrender.config.json` generan una advertencia con la opción
+  correcta sugerida.
 - En Ubuntu 23.10+ el navegador descargado con `mdrender setup` no puede usar el sandbox de
   Chrome (restricción de AppArmor); mdrender lo inicia entonces sin sandbox, lo que es seguro
   aquí porque las páginas no ejecutan JavaScript del documento ni acceden a la red
@@ -231,7 +289,8 @@ El CI (GitHub Actions) prueba en **Windows y Linux** con Node 22 y 24, construye
 ejecutable y valida `mdrender setup`. Para publicar una versión, sube una etiqueta `v*` o
 lanza a mano **Actions → Release → Run workflow** con la versión (debe coincidir con
 `package.json`): construye los ejecutables, crea la etiqueta y el GitHub Release con sus sumas
-SHA-256, y publica en npm si el secreto `NPM_TOKEN` está configurado.
+SHA-256, y publica en npm. Requiere el secreto de repositorio `NPM_TOKEN`; si falta, la
+publicación se detiene al inicio, antes de publicar nada.
 
 Plan completo y decisiones de diseño: [docs/PLAN_MAESTRO.md](docs/PLAN_MAESTRO.md) ·
 cambios: [CHANGELOG.md](CHANGELOG.md).

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";
@@ -12,12 +13,20 @@ import { watchAndConvert } from "./watch.js";
 const DOCUMENT_FLAGS = [
     "pageSize",
     "margin",
+    "marginTop",
+    "marginRight",
+    "marginBottom",
+    "marginLeft",
+    // --landscape before --orientation so an explicit --orientation wins.
     "landscape",
+    "orientation",
     "toc",
     "tocDepth",
     "header",
     "footer",
     "pageNumbers",
+    "density",
+    "fontSize",
     "css",
     "theme",
     "mermaidTheme",
@@ -33,14 +42,21 @@ const collect = (value, previous = []) => [...previous, value];
 /** Options shared by `mdrender` (render) and `mdrender preview`. */
 function addDocumentOptions(command) {
     return command
-        .option("--page-size <size>", `paper size: ${PAGE_SIZES.join(", ")} (default: A4)`)
-        .option("--margin <margin>", 'page margins, e.g. "20mm" or "15mm 20mm" (default: 20mm)')
-        .option("--landscape", "landscape orientation")
+        .option("--page-size <size>", `paper size: ${PAGE_SIZES.join(", ")} (default: Letter)`)
+        .option("--orientation <orientation>", "portrait or landscape (default: portrait)")
+        .option("--landscape", "same as --orientation landscape")
+        .option("--margin <margin>", 'all page margins, CSS-style: "10mm", "15mm 20mm"… (default: 10mm)')
+        .option("--margin-top <length>", "top margin, e.g. 15mm (overrides --margin)")
+        .option("--margin-right <length>", "right margin")
+        .option("--margin-bottom <length>", "bottom margin")
+        .option("--margin-left <length>", "left margin")
         .option("--toc", "insert a table of contents (or place it with [[toc]])")
         .option("--toc-depth <n>", "deepest heading level in the table of contents (default: 3)")
         .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)`)
@@ -69,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.
@@ -132,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);
@@ -181,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/config.d.ts

@@ -2,5 +2,12 @@ import { type DocumentOptions } from "./options.js";
 export declare const CONFIG_FILE = "mdrender.config.json";
 /** Find `mdrender.config.json` in `startDir` or the nearest parent directory. */
 export declare function findConfigFile(startDir: string): string | undefined;
+export interface LoadedConfig {
+    options: Partial<DocumentOptions>;
+    /** Problems that do not stop the conversion, such as misspelled option names. */
+    warnings: string[];
+}
 /** Read and validate a config file. Relative paths inside it resolve against its folder. */
 export declare function loadConfig(file: string): Partial<DocumentOptions>;
+/** Like `loadConfig`, also reporting unknown option names (likely typos). */
+export declare function readConfig(file: string): LoadedConfig;

package/dist/config.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { normalizeOptions, OptionsError } from "./options.js";
+import { normalizeOptions, OptionsError, unknownOptions } from "./options.js";
 export const CONFIG_FILE = "mdrender.config.json";
 /** Find `mdrender.config.json` in `startDir` or the nearest parent directory. */
 export function findConfigFile(startDir) {
@@ -17,6 +17,10 @@ export function findConfigFile(startDir) {
 }
 /** Read and validate a config file. Relative paths inside it resolve against its folder. */
 export function loadConfig(file) {
+    return readConfig(file).options;
+}
+/** Like `loadConfig`, also reporting unknown option names (likely typos). */
+export function readConfig(file) {
     let raw;
     try {
         raw = JSON.parse(readFileSync(file, "utf8"));
@@ -27,6 +31,11 @@ export function loadConfig(file) {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
         throw new OptionsError(`${file}: the configuration must be a JSON object`);
     }
-    return normalizeOptions(raw, file, path.dirname(file));
+    const record = raw;
+    const relative = path.relative(process.cwd(), file);
+    const shown = relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : file;
+    const warnings = unknownOptions(record).map(({ key, suggestion }) => `${shown}: unknown option "${key}"` +
+        (suggestion ? ` (did you mean "${suggestion}"?)` : " (ignored)"));
+    return { options: normalizeOptions(record, file, path.dirname(file)), warnings };
 }
 //# sourceMappingURL=config.js.map

package/dist/convert.d.ts

@@ -1,5 +1,5 @@
 import type { Diagnostic } from "./diagnostics.js";
-import { type DocumentOptions, type MermaidTheme } from "./options.js";
+import { type DocumentOptions, type Margins, type MermaidTheme } from "./options.js";
 import type { OutputFormat } from "./paths.js";
 import { BrowserSession } from "./render/browser.js";
 /** Settings shared by every file of a run (batch, watch or preview). */
@@ -53,6 +53,12 @@ export declare class BrowserPool {
     get(): Promise<BrowserSession>;
     close(): Promise<void>;
 }
+/**
+ * Chrome draws the header and footer inside the top and bottom margins. Measured: below about
+ * 10 mm the header touches or overlaps the first line of text (and the footer the last line).
+ */
+export declare const MIN_HEADER_FOOTER_MARGIN = "10mm";
+export declare function headerFooterSpaceWarnings(margin: Margins, hasHeader: boolean, hasFooter: boolean): Diagnostic[];
 /** Mermaid theme: explicit choice, else dark diagrams for the dark page theme. */
 export declare function effectiveMermaidTheme(options: DocumentOptions): MermaidTheme;
 /**

package/dist/convert.js

@@ -1,18 +1,19 @@
 import { readFileSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { findBrowser } from "./browser/detect.js";
-import { findConfigFile, loadConfig } from "./config.js";
+import { findConfigFile, readConfig } from "./config.js";
 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, parseMargin, } 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 } 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 {
     executable;
@@ -51,6 +52,40 @@ function readStylesheet(file) {
 function themeStylesheets(theme) {
     return theme === "light" || theme === "dark" ? builtinThemeCss(theme) : [readStylesheet(theme)];
 }
+/**
+ * Chrome draws the header and footer inside the top and bottom margins. Measured: below about
+ * 10 mm the header touches or overlaps the first line of text (and the footer the last line).
+ */
+export const MIN_HEADER_FOOTER_MARGIN = "10mm";
+export function headerFooterSpaceWarnings(margin, hasHeader, hasFooter) {
+    const minimum = lengthToPx(MIN_HEADER_FOOTER_MARGIN);
+    const warnings = [];
+    // Half a pixel of slack: "0.39in" and "10mm" are the same margin once Chrome rounds them.
+    if (hasHeader && lengthToPx(margin.top) < minimum - 0.5) {
+        warnings.push({
+            severity: "warning",
+            message: `the header may overlap the text: top margin is ${margin.top}, ` +
+                `at least ${MIN_HEADER_FOOTER_MARGIN} is needed (e.g. --margin-top 15mm)`,
+        });
+    }
+    if (hasFooter && lengthToPx(margin.bottom) < minimum - 0.5) {
+        warnings.push({
+            severity: "warning",
+            message: `the footer may overlap the text: bottom margin is ${margin.bottom}, ` +
+                `at least ${MIN_HEADER_FOOTER_MARGIN} is needed ` +
+                "(e.g. --margin-bottom 15mm, or --no-page-numbers for no footer)",
+        });
+    }
+    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");
@@ -69,12 +104,16 @@ export async function renderDocument(inputPath, settings, browsers) {
         : settings.config
             ? path.resolve(settings.config)
             : findConfigFile(baseDir);
-    const options = mergeOptions(configFile ? loadConfig(configFile) : {}, normalizeOptions(frontMatter.data, `${input} (front matter)`, baseDir), settings.overrides ?? {});
-    const margin = parseMargin(options.margin);
+    const config = configFile ? readConfig(configFile) : { options: {}, warnings: [] };
+    const options = mergeOptions(config.options, normalizeOptions(frontMatter.data, `${input} (front matter)`, baseDir), settings.overrides ?? {});
+    const margin = resolveMargins(options);
     const themeCss = themeStylesheets(options.theme);
     const extraCss = options.css.map(readStylesheet);
     const md = renderMarkdown(frontMatter.body, { baseDir, lang: options.lang });
-    const diagnostics = [...md.diagnostics];
+    const diagnostics = [
+        ...config.warnings.map((message) => ({ severity: "warning", message })),
+        ...md.diagnostics,
+    ];
     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;
@@ -88,9 +127,10 @@ export async function renderDocument(inputPath, settings, browsers) {
     // Mermaid needs a real DOM to lay out diagrams, also for HTML output.
     if (md.mermaid.length > 0) {
         const session = await browsers.get();
-        const width = contentWidthPx(options.pageSize, options.landscape, margin);
+        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);
@@ -105,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));
@@ -122,17 +163,16 @@ export async function convertFile(convert) {
     try {
         const doc = await renderDocument(convert.input, convert, browsers);
         const { options } = doc;
-        await mkdir(path.dirname(output), { recursive: true });
         if (convert.format === "pdf") {
-            const margin = parseMargin(options.margin);
+            const margin = resolveMargins(options);
             const values = { title: doc.title, author: options.author, date: options.date };
             const footer = options.footer ?? (options.pageNumbers ? DEFAULT_FOOTER : undefined);
             const hasHeaderFooter = options.header !== undefined || footer !== undefined;
+            doc.diagnostics.push(...headerFooterSpaceWarnings(margin, options.header !== undefined, footer !== undefined));
             const session = await browsers.get();
-            const { blocked } = await session.printPdf(doc.html, {
-                output,
+            const { pdf, blocked } = await session.printPdf(doc.html, {
                 format: options.pageSize,
-                landscape: options.landscape,
+                landscape: options.orientation === "landscape",
                 margin,
                 headerTemplate: hasHeaderFooter
                     ? headerFooterTemplate(options.header, values, margin)
@@ -147,9 +187,10 @@ export async function convertFile(convert) {
                     message: `resource not loaded: ${url}${hint}`,
                 });
             }
+            await writeFileAtomic(output, pdf);
         }
         else {
-            await writeFile(output, doc.html, "utf8");
+            await writeFileAtomic(output, doc.html);
         }
         return {
             output,