@imontene/mdrender 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Cambios
 
+## 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
+  (por ejemplo `mdrender --help | head`); ahora el comando termina normalmente.
+- El flujo de publicación se puede lanzar a mano con la versión
+  (Actions → Release → Run workflow).
+
 ## 1.0.0 — 2026-10-04
 
 Primera versión estable.

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
@@ -109,30 +109,42 @@ 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                            | —                  |
+| `--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.
 
 **Encabezado y pie**: texto con marcadores `{page}`, `{pages}`, `{title}`, `{author}` y
 `{date}`; `|` separa columnas izquierda, centro y derecha. Ejemplos:
@@ -151,7 +163,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 +173,9 @@ header: "{title} | | {date}"
 ```json
 {
   "lang": "es",
-  "pageSize": "A4",
-  "margin": "25mm 20mm",
+  "pageSize": "Letter",
+  "margin": "15mm",
+  "marginLeft": "25mm",
   "css": "estilos/empresa.css"
 }
 ```
@@ -199,6 +214,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 +250,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/bin.js

@@ -4,6 +4,12 @@ import { defaultIo, main } from "./cli.js";
 const controller = new AbortController();
 process.once("SIGINT", () => controller.abort());
 process.once("SIGTERM", () => controller.abort());
+// A reader that stops early (`mdrender --help | head`) closes the pipe: drop the rest of the
+// output instead of crashing with an unhandled EPIPE.
+process.stdout.on("error", (error) => {
+    if (error.code !== "EPIPE")
+        throw error;
+});
 main(process.argv.slice(2), defaultIo, { signal: controller.signal }).then((code) => {
     process.exitCode = code;
     // Leftover handles (e.g. a keep-alive proxy connection after `setup`) must not keep the CLI

package/dist/cli.js

@@ -12,7 +12,13 @@ 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",
@@ -33,9 +39,14 @@ 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}"')

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 { 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 { contentWidthPx, lengthToPx } from "./render/page.js";
 import { buildHtmlDocument, builtinThemeCss } 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,32 @@ 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;
+}
 /** 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 +96,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,7 +119,7 @@ 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 filled = fillMermaid(body, md.nonce, md.mermaid, results);
@@ -122,17 +153,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 +177,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,

package/dist/inputs.js

@@ -95,7 +95,7 @@ export function planOutputs(inputs, format, output, cwd = process.cwd()) {
         if (several) {
             throw new OptionsError(`with several input files, --output must be a folder: ${output}`);
         }
-        return [{ input: inputs[0].file, output: outDir }];
+        return checkJobs([{ input: inputs[0].file, output: outDir }], inputs);
     }
     const jobs = inputs.map(({ file, root }) => {
         const name = path.parse(file).name + ext;
@@ -104,9 +104,22 @@ export function planOutputs(inputs, format, output, cwd = process.cwd()) {
         const relativeDir = root ? path.relative(root, path.dirname(file)) : "";
         return { input: file, output: path.join(outDir, relativeDir, name) };
     });
+    return checkJobs(jobs, inputs);
+}
+/** Path comparison key: Windows paths are case-insensitive. */
+const pathKey = (file) => process.platform === "win32" ? path.resolve(file).toLowerCase() : path.resolve(file);
+/**
+ * Refuse plans that would destroy data: an output that is one of the input Markdown files
+ * (`mdrender doc.md -o doc.md`), or two inputs written to the same output.
+ */
+function checkJobs(jobs, inputs) {
+    const sources = new Set(inputs.map(({ file }) => pathKey(file)));
     const targets = new Map();
     for (const job of jobs) {
-        const key = process.platform === "win32" ? job.output.toLowerCase() : job.output;
+        const key = pathKey(job.output);
+        if (sources.has(key)) {
+            throw new OptionsError(`refusing to overwrite the input file ${job.output}; choose another --output`);
+        }
         const other = targets.get(key);
         if (other) {
             throw new OptionsError(`${other} and ${job.input} would both be written to ${job.output}`);

package/dist/options.d.ts

@@ -1,6 +1,14 @@
 import { MdRenderError } from "./errors.js";
 export declare const PAGE_SIZES: readonly ["A3", "A4", "A5", "Letter", "Legal", "Tabloid"];
 export type PageSize = (typeof PAGE_SIZES)[number];
+export declare const ORIENTATIONS: readonly ["portrait", "landscape"];
+export type Orientation = (typeof ORIENTATIONS)[number];
+export type Margins = {
+    top: string;
+    right: string;
+    bottom: string;
+    left: string;
+};
 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"];
@@ -9,7 +17,12 @@ export interface DocumentOptions {
     pageSize: PageSize;
     /** CSS margin shorthand: 1 to 4 lengths in mm, cm, in or px. */
     margin: string;
-    landscape: boolean;
+    /** Single sides, overriding the shorthand (see `resolveMargins`). */
+    marginTop?: string;
+    marginRight?: string;
+    marginBottom?: string;
+    marginLeft?: string;
+    orientation: Orientation;
     toc: boolean;
     /** Deepest heading level listed in the table of contents. */
     tocDepth: number;
@@ -36,12 +49,7 @@ export declare class OptionsError extends MdRenderError {
     constructor(message: string);
 }
 /** Parse a CSS margin shorthand into the four sides, or throw. */
-export declare function parseMargin(margin: string): {
-    top: string;
-    right: string;
-    bottom: string;
-    left: string;
-};
+export declare function parseMargin(margin: string): Margins;
 /**
  * Validate options from a config file, front matter or the command line.
  *
@@ -51,5 +59,23 @@ export declare function parseMargin(margin: string): {
 export declare function normalizeOptions(raw: Record<string, unknown>, source: string, baseDir: string, 
 /** How to name a key in error messages (e.g. as a command-line flag). */
 label?: (key: string) => string): Partial<DocumentOptions>;
-/** Merge option layers, later ones winning. CSS lists accumulate instead of replacing. */
+/**
+ * Merge option layers, later ones winning. CSS lists accumulate instead of replacing. A layer
+ * that sets the `margin` shorthand also replaces single-side margins from earlier layers, so
+ * `--margin 15mm` on the command line is not partly undone by `marginLeft` in a config file.
+ */
 export declare function mergeOptions(...layers: Partial<DocumentOptions>[]): DocumentOptions;
+/** The four page margins: the `margin` shorthand, with single-side options on top. */
+export declare function resolveMargins(options: DocumentOptions): Margins;
+/** Every option name accepted in a config file, in camelCase. */
+export declare const OPTION_KEYS: readonly string[];
+export interface UnknownOption {
+    key: string;
+    /** Closest known option, written in the same style (camelCase or kebab-case) as `key`. */
+    suggestion?: string;
+}
+/**
+ * Keys that are not options, with the closest known option when one is near: catches typos
+ * such as "pagesize" or "margn" that would otherwise be ignored silently.
+ */
+export declare function unknownOptions(raw: Record<string, unknown>): UnknownOption[];

package/dist/options.js

@@ -3,12 +3,13 @@ import { ExitCode } from "./exit-codes.js";
 import { MdRenderError } from "./errors.js";
 import { DEFAULT_LANG } from "./i18n.js";
 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 DEFAULT_OPTIONS = {
-    pageSize: "A4",
-    margin: "20mm",
-    landscape: false,
+    pageSize: "Letter",
+    margin: "10mm",
+    orientation: "portrait",
     toc: false,
     tocDepth: 3,
     pageNumbers: true,
@@ -51,6 +52,13 @@ const oneOf = (choices) => (value, describe) => {
         return match;
     throw new OptionsError(`${describe} must be one of: ${choices.join(", ")}`);
 };
+const length = (value, describe) => {
+    const raw = text(value, describe, "");
+    const trimmed = raw.trim();
+    if (LENGTH.test(trimmed))
+        return trimmed;
+    throw new OptionsError(`${describe} must be a length in mm, cm, in or px, e.g. "10mm"`);
+};
 const VALIDATORS = {
     pageSize: oneOf(PAGE_SIZES),
     margin: (value, describe) => {
@@ -63,7 +71,11 @@ const VALIDATORS = {
         }
         return margin;
     },
-    landscape: bool,
+    marginTop: length,
+    marginRight: length,
+    marginBottom: length,
+    marginLeft: length,
+    orientation: oneOf(ORIENTATIONS),
     toc: bool,
     tocDepth: (value, describe) => {
         const depth = Number(value);
@@ -109,6 +121,12 @@ label = (key) => `"${key}"`) {
     for (const [key, value] of Object.entries(raw)) {
         if (value === undefined || value === null)
             continue;
+        // `landscape: true` is kept as a shorthand for `orientation: landscape`.
+        if (toCamel(key) === "landscape") {
+            const landscape = bool(value, `${source}: ${label(key)}`, baseDir);
+            result.orientation = landscape ? "landscape" : "portrait";
+            continue;
+        }
         const name = toCamel(key);
         const validate = VALIDATORS[name];
         if (!validate)
@@ -117,15 +135,74 @@ label = (key) => `"${key}"`) {
     }
     return result;
 }
-/** Merge option layers, later ones winning. CSS lists accumulate instead of replacing. */
+const SIDES = ["marginTop", "marginRight", "marginBottom", "marginLeft"];
+/**
+ * Merge option layers, later ones winning. CSS lists accumulate instead of replacing. A layer
+ * that sets the `margin` shorthand also replaces single-side margins from earlier layers, so
+ * `--margin 15mm` on the command line is not partly undone by `marginLeft` in a config file.
+ */
 export function mergeOptions(...layers) {
     const merged = { ...DEFAULT_OPTIONS, css: [] };
     for (const layer of layers) {
         const { css, ...rest } = layer;
+        if (rest.margin !== undefined)
+            for (const side of SIDES)
+                delete merged[side];
         Object.assign(merged, rest);
         if (css)
             merged.css.push(...css);
     }
     return merged;
 }
+/** The four page margins: the `margin` shorthand, with single-side options on top. */
+export function resolveMargins(options) {
+    const base = parseMargin(options.margin);
+    return {
+        top: options.marginTop ?? base.top,
+        right: options.marginRight ?? base.right,
+        bottom: options.marginBottom ?? base.bottom,
+        left: options.marginLeft ?? base.left,
+    };
+}
+/** Edit distance between two strings (insertions, deletions, substitutions). */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+const toKebab = (key) => key.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+/** Every option name accepted in a config file, in camelCase. */
+export const OPTION_KEYS = [...Object.keys(VALIDATORS), "landscape"];
+/**
+ * Keys that are not options, with the closest known option when one is near: catches typos
+ * such as "pagesize" or "margn" that would otherwise be ignored silently.
+ */
+export function unknownOptions(raw) {
+    const unknown = [];
+    for (const key of Object.keys(raw)) {
+        if (OPTION_KEYS.includes(toCamel(key)))
+            continue;
+        const plain = key.toLowerCase().replace(/[-_]/g, "");
+        let best;
+        let bestDistance = Infinity;
+        for (const known of OPTION_KEYS) {
+            const distance = editDistance(plain, known.toLowerCase());
+            if (distance < bestDistance) {
+                best = known;
+                bestDistance = distance;
+            }
+        }
+        const close = best !== undefined && bestDistance <= Math.max(1, Math.floor(plain.length / 4));
+        const suggestion = close ? (key.includes("-") ? toKebab(best) : best) : undefined;
+        unknown.push({ key, suggestion });
+    }
+    return unknown;
+}
 //# sourceMappingURL=options.js.map

package/dist/render/browser.d.ts

@@ -8,7 +8,6 @@ import { type Page, type PDFOptions } from "puppeteer-core";
  */
 export declare function shouldRetryWithoutSandbox(error: unknown, args: string[], platform?: NodeJS.Platform): boolean;
 export interface PrintOptions {
-    output: string;
     format?: PDFOptions["format"];
     landscape?: boolean;
     margin?: {
@@ -41,7 +40,9 @@ export declare class BrowserSession {
      * rendered by then (math by KaTeX, diagrams by Mermaid), and any <script> in the Markdown
      * must not run.
      */
+    /** Returns the PDF bytes (the caller writes them) and the URLs that were blocked. */
     printPdf(html: string, options: PrintOptions): Promise<{
+        pdf: Uint8Array;
         blocked: string[];
     }>;
     close(): Promise<void>;

package/dist/render/browser.js

@@ -93,8 +93,9 @@ export class BrowserSession {
      * rendered by then (math by KaTeX, diagrams by Mermaid), and any <script> in the Markdown
      * must not run.
      */
+    /** Returns the PDF bytes (the caller writes them) and the URLs that were blocked. */
     async printPdf(html, options) {
-        const margin = options.margin ?? { top: "20mm", right: "20mm", bottom: "20mm", left: "20mm" };
+        const margin = options.margin ?? { top: "10mm", right: "10mm", bottom: "10mm", left: "10mm" };
         const headerFooter = options.headerTemplate !== undefined || options.footerTemplate !== undefined;
         const page = await this.browser.newPage();
         page.setDefaultTimeout(this.timeout);
@@ -104,8 +105,7 @@ export class BrowserSession {
             await page.setContent(html, { waitUntil: "load" });
             // Make sure every embedded font has loaded before printing.
             await page.evaluate("document.fonts.ready.then(() => undefined)");
-            await page.pdf({
-                path: options.output,
+            const pdf = await page.pdf({
                 format: options.format ?? "A4",
                 landscape: options.landscape ?? false,
                 margin,
@@ -118,7 +118,7 @@ export class BrowserSession {
                 tagged: true,
                 timeout: this.timeout,
             });
-            return { blocked: [...new Set(blocked)] };
+            return { pdf, blocked: [...new Set(blocked)] };
         }
         catch (error) {
             throw new RenderError(`failed to render PDF: ${error.message}`);

package/dist/write.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Write a file all at once: the content goes to a hidden temporary file in the same folder,
+ * which then replaces the target. An interrupted or failed conversion never leaves a truncated
+ * file and keeps the previous version.
+ *
+ * On Windows a file open in another program (a PDF viewer) cannot be replaced; short-lived locks
+ * (antivirus, indexing) are retried before reporting it.
+ */
+export declare function writeFileAtomic(file: string, data: string | Uint8Array): Promise<void>;

package/dist/write.js

@@ -0,0 +1,41 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { RenderError } from "./errors.js";
+const BUSY = new Set(["EPERM", "EBUSY", "EACCES"]);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Write a file all at once: the content goes to a hidden temporary file in the same folder,
+ * which then replaces the target. An interrupted or failed conversion never leaves a truncated
+ * file and keeps the previous version.
+ *
+ * On Windows a file open in another program (a PDF viewer) cannot be replaced; short-lived locks
+ * (antivirus, indexing) are retried before reporting it.
+ */
+export async function writeFileAtomic(file, data) {
+    const dir = path.dirname(file);
+    await mkdir(dir, { recursive: true });
+    const temp = path.join(dir, `.${path.basename(file)}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        await writeFile(temp, data);
+        for (let attempt = 1;; attempt++) {
+            try {
+                await rename(temp, file);
+                return;
+            }
+            catch (error) {
+                const code = error.code ?? "";
+                if (!BUSY.has(code) || attempt >= 5)
+                    throw error;
+                await sleep(100 * attempt);
+            }
+        }
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        const code = error.code ?? "";
+        const hint = BUSY.has(code) ? " (is it open in another program, such as a PDF viewer?)" : "";
+        throw new RenderError(`cannot write ${file}: ${error.message}${hint}`);
+    }
+}
+//# sourceMappingURL=write.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imontene/mdrender",
-  "version": "1.0.0",
+  "version": "2.0.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",