@imontene/mdrender 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Cambios
 
+## 2.4.0 — 2026-10-22
+
+- **Párrafos justificados en el PDF**: los del texto, las citas y las alertas, con partición de
+  palabras según el idioma del documento (español, inglés, portugués, francés, alemán e
+  italiano). Listas, tablas, notas al pie, índice y diagramas siguen alineados a la izquierda,
+  y el HTML no cambia. `--no-justify` (o `justify: false`) lo desactiva. El texto del PDF solo
+  lleva el guion donde una palabra se corta: copiar y buscar siguen funcionando.
+
 ## 2.3.0 — 2026-10-16
 
 - **Manrope es la nueva tipografía por defecto** del texto, el encabezado, el pie y los

package/README.md

@@ -153,6 +153,7 @@ equipo); `--port` fija el puerto y `--no-open` no abre el navegador.
 | `--footer <texto>`             | Pie de página (ver abajo)                                            | `{page} / {pages}` |
 | `--no-page-numbers`            | Sin el pie con números de página                                     | —                  |
 | `--font <manrope\|inter>`      | Tipografía del texto (ver abajo)                                     | `manrope`          |
+| `--no-justify`                 | Párrafos alineados a la izquierda en el PDF (ver abajo)              | justificado        |
 | `--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`            |
@@ -184,6 +185,14 @@ Ambas van incrustadas en el PDF, también en el encabezado, el pie y los diagram
 tiene cursivas (el navegador inclina la normal) ni algunos símbolos como `→`, `✓` o `≤`, que
 se toman de Inter.
 
+**Párrafos justificados**: en el PDF, los párrafos del texto, de las citas y de las alertas
+se justifican, y las palabras largas se parten con guion al final de la línea según el idioma
+del documento (`lang`: español, inglés, portugués, francés, alemán o italiano; en otros idiomas
+se justifica sin partir palabras). Listas, tablas, notas al pie, el índice y los diagramas
+quedan alineados a la izquierda, igual que el HTML. El texto del PDF solo lleva el guion donde
+la palabra se corta, así que copiar y buscar funcionan con las palabras completas.
+`--no-justify` (o `justify: false`) vuelve a alinear a la izquierda.
+
 **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:

package/dist/cli.js

@@ -26,6 +26,7 @@ const DOCUMENT_FLAGS = [
     "footer",
     "pageNumbers",
     "font",
+    "justify",
     "density",
     "fontSize",
     "css",
@@ -36,6 +37,8 @@ const DOCUMENT_FLAGS = [
     "lang",
     "title",
 ];
+/** Options set on the command line only through their --no-… form. */
+const NEGATED_FLAGS = new Set(["pageNumbers", "mermaidAutofit", "justify"]);
 const toFlag = (key) => "--" + key.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
 export const defaultIo = {
     out: (text) => process.stdout.write(text),
@@ -59,6 +62,7 @@ function addDocumentOptions(command) {
         .option("--footer <text>", 'page footer (default: "{page} / {pages}")')
         .option("--no-page-numbers", "no default page-number footer")
         .option("--font <font>", "text typeface: manrope or inter (default: manrope)")
+        .option("--no-justify", "align paragraphs left in the PDF instead of justifying them")
         .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)")
@@ -117,11 +121,7 @@ function cliOverrides(program) {
         if (program.getOptionValueSource(key) === "cli")
             raw[key] = program.getOptionValue(key);
     }
-    return normalizeOptions(raw, "command line", process.cwd(), (key) => key === "pageNumbers"
-        ? "--no-page-numbers"
-        : key === "mermaidAutofit"
-            ? "--no-mermaid-autofit"
-            : toFlag(key));
+    return normalizeOptions(raw, "command line", process.cwd(), (key) => NEGATED_FLAGS.has(key) ? `--no-${toFlag(key).slice(2)}` : toFlag(key));
 }
 function settings(program, options) {
     return {

package/dist/convert.js

@@ -13,7 +13,7 @@ import { DEFAULT_FOOTER, headerFooterTemplate } from "./render/header-footer.js"
 import { fillMermaid, renderMermaid } from "./render/mermaid.js";
 import { SMALL_SCALE } from "./render/mermaid-fit.js";
 import { FONT_FAMILIES, fontStack } from "./render/fonts.js";
-import { contentHeightPx, contentWidthPx, lengthToPx } from "./render/page.js";
+import { contentHeightPx, contentWidthPx, lengthToPx, textWidthPx } 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. */
@@ -80,6 +80,18 @@ export function headerFooterSpaceWarnings(margin, hasHeader, hasFooter) {
     }
     return warnings;
 }
+/**
+ * Justified paragraphs in the PDF: the body's, and those directly inside a quote or an alert
+ * (the same ones markdown/hyphenate.ts gives soft hyphens). Lists, tables, footnotes, the title
+ * block, the table of contents and diagram labels stay aligned left. Print only: on screen the
+ * HTML keeps ragged lines.
+ */
+const JUSTIFY_CSS = `@media print {
+  .markdown-body > p,
+  .markdown-body > blockquote > p:not(.markdown-alert-title) {
+    text-align: justify;
+  }
+}`;
 /** 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);
@@ -93,6 +105,8 @@ function layoutCss(options, margin) {
     // heading is pushed to the next page, Chrome then repeats its text in the PDF bookmark.
     if (options.font === "manrope")
         rules.push("h1, h2, h3, h4, h5, h6 { line-height: 1.4; }");
+    if (options.justify)
+        rules.push(JUSTIFY_CSS);
     if (options.fontSize)
         rules.push(`html { font-size: ${options.fontSize}; }`);
     return rules.join("\n");
@@ -135,7 +149,12 @@ paged = false) {
     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 md = renderMarkdown(frontMatter.body, {
+        baseDir,
+        lang: options.lang,
+        // Soft hyphens only where paragraphs are justified: in the PDF.
+        hyphenate: paged && options.justify ? options.lang : undefined,
+    });
     const diagnostics = [
         ...config.warnings.map((message) => ({ severity: "warning", message })),
         ...md.diagnostics,
@@ -236,6 +255,9 @@ export async function convertFile(convert) {
                     ? headerFooterTemplate(footer, values, margin, options.font)
                     : undefined,
                 allowRemote: convert.allowRemote,
+                softHyphensWidthPx: options.justify
+                    ? textWidthPx(options.pageSize, options.orientation === "landscape", margin)
+                    : undefined,
             });
             for (const url of blocked) {
                 const hint = /^https?:/i.test(url) ? " (use --allow-remote to download it)" : "";

package/dist/doctor.js

@@ -137,6 +137,7 @@ function settingsCheck(options) {
         detail: `${options.pageSize} ${options.orientation}, margins ${m.top} ${m.right} ${m.bottom} ` +
             `${m.left} (top right bottom left), ${options.font} ` +
             `${options.fontSize ?? DEFAULT_FONT_SIZE}, ${options.density} density, ` +
+            `${options.justify ? "justified" : "ragged"} paragraphs, ` +
             `language ${options.lang}, theme ` +
             path.basename(options.theme),
     };

package/dist/markdown/env.d.ts

@@ -22,6 +22,8 @@ export interface RenderEnv extends Env {
     hasMath: boolean;
     /** Document language, for translated labels (alert titles). */
     lang: string;
+    /** Language whose hyphenation patterns break justified paragraphs (PDF only); see hyphenate.ts. */
+    hyphenate?: string;
     /** Set when the document places its table of contents with a `[[toc]]` marker. */
     hasTocMarker: boolean;
 }

package/dist/markdown/hyphenate.d.ts

@@ -0,0 +1,14 @@
+import type { MarkdownIt } from "markdown-it";
+/**
+ * Soft hyphens (U+00AD) for justified paragraphs in the PDF, so the browser can break long
+ * words at the end of a line instead of stretching the spaces. They are inserted here, from TeX
+ * hyphenation patterns, because CSS `hyphens: auto` depends on dictionaries that Chromium and
+ * Chrome Headless Shell do not ship. When printing, the soft hyphens that did not end up at the
+ * end of a line are removed again (render/browser.ts), so they stay out of the PDF's text.
+ */
+export declare const SOFT_HYPHEN = "\u00AD";
+export declare const HYPHENATION_LANGUAGES: string[];
+/** Hyphenation function for a BCP 47 language tag ("es", "es-CL", "en-GB"), if supported. */
+export declare function hyphenatorFor(lang: string): ((text: string) => string) | undefined;
+/** Insert soft hyphens in the paragraphs that are justified in the PDF (env.hyphenate). */
+export declare function hyphenation(md: MarkdownIt): void;

package/dist/markdown/hyphenate.js

@@ -0,0 +1,92 @@
+import createHyphenator from "hyphen";
+import de from "hyphen/patterns/de-1996.js";
+import enGb from "hyphen/patterns/en-gb.js";
+import enUs from "hyphen/patterns/en-us.js";
+import es from "hyphen/patterns/es.js";
+import fr from "hyphen/patterns/fr.js";
+import it from "hyphen/patterns/it.js";
+import pt from "hyphen/patterns/pt.js";
+/**
+ * Soft hyphens (U+00AD) for justified paragraphs in the PDF, so the browser can break long
+ * words at the end of a line instead of stretching the spaces. They are inserted here, from TeX
+ * hyphenation patterns, because CSS `hyphens: auto` depends on dictionaries that Chromium and
+ * Chrome Headless Shell do not ship. When printing, the soft hyphens that did not end up at the
+ * end of a line are removed again (render/browser.ts), so they stay out of the PDF's text.
+ */
+export const SOFT_HYPHEN = "­";
+/** Hyphenation patterns by language: base language, or language-region where they differ. */
+const PATTERNS = {
+    es,
+    en: enUs,
+    "en-gb": enGb,
+    pt,
+    fr,
+    de,
+    it,
+};
+export const HYPHENATION_LANGUAGES = Object.keys(PATTERNS);
+const hyphenators = new Map();
+/** Hyphenation function for a BCP 47 language tag ("es", "es-CL", "en-GB"), if supported. */
+export function hyphenatorFor(lang) {
+    const tag = lang.trim().toLowerCase().replace(/_/g, "-");
+    const patterns = PATTERNS[tag.split("-").slice(0, 2).join("-")] ?? PATTERNS[tag.split("-")[0]];
+    if (!patterns)
+        return undefined;
+    let hyphenate = hyphenators.get(patterns);
+    if (!hyphenate) {
+        // The input is plain text from Markdown, not HTML (a literal "<" is just a character).
+        const sync = createHyphenator(patterns, { html: false });
+        hyphenate = (text) => sync(text);
+        hyphenators.set(patterns, hyphenate);
+    }
+    return hyphenate;
+}
+/**
+ * Whether a paragraph is justified: top-level, or directly inside a blockquote or alert (the
+ * same paragraphs as the print stylesheet in convert.ts). Lists, footnotes and tables are not.
+ */
+function justified(containers) {
+    return (containers.length === 0 || (containers.length === 1 && containers[0] === "blockquote_open"));
+}
+function hyphenateInline(inline, hyphenate) {
+    let inAutolink = 0;
+    for (const child of inline.children ?? []) {
+        if (child.type === "link_open" && (child.markup === "linkify" || child.markup === "autolink")) {
+            inAutolink++;
+        }
+        else if (child.type === "link_close" && inAutolink > 0) {
+            inAutolink--;
+        }
+        else if (child.type === "text" && inAutolink === 0) {
+            child.content = hyphenate(child.content);
+        }
+    }
+}
+/** Insert soft hyphens in the paragraphs that are justified in the PDF (env.hyphenate). */
+export function hyphenation(md) {
+    md.core.ruler.push("hyphenation", (state) => {
+        const lang = state.env.hyphenate;
+        const hyphenate = lang === undefined ? undefined : hyphenatorFor(lang);
+        if (!hyphenate)
+            return;
+        const containers = [];
+        for (let i = 0; i < state.tokens.length; i++) {
+            const token = state.tokens[i];
+            if (token.type === "paragraph_open") {
+                const inline = state.tokens[i + 1];
+                if (justified(containers) && inline?.type === "inline")
+                    hyphenateInline(inline, hyphenate);
+            }
+            else if (token.type === "paragraph_close") {
+                continue;
+            }
+            else if (token.nesting === 1) {
+                containers.push(token.type);
+            }
+            else if (token.nesting === -1) {
+                containers.pop();
+            }
+        }
+    });
+}
+//# sourceMappingURL=hyphenate.js.map

package/dist/markdown/index.d.ts

@@ -22,6 +22,8 @@ export interface MarkdownOptions {
     baseDir?: string;
     /** Document language for translated labels. Defaults to Spanish. */
     lang?: string;
+    /** Insert soft hyphens in justified paragraphs, with this language's patterns. */
+    hyphenate?: string;
 }
 export declare function createMarkdown(): MarkdownIt;
 export declare function renderMarkdown(source: string, options?: MarkdownOptions): MarkdownResult;

package/dist/markdown/index.js

@@ -7,6 +7,7 @@ import { alerts } from "./alerts.js";
 import { codeBlocks } from "./code-blocks.js";
 import { inlineChildLines } from "./env.js";
 import { highlightCode } from "./highlight.js";
+import { hyphenation } from "./hyphenate.js";
 import { inlineLocalImages } from "./images.js";
 import { keepWithHeading } from "./keep-with-heading.js";
 import { math } from "./math.js";
@@ -32,6 +33,7 @@ export function createMarkdown() {
     md.use(codeBlocks);
     md.use(math);
     md.use(mermaid);
+    md.use(hyphenation);
     return md;
 }
 let shared;
@@ -46,6 +48,7 @@ export function renderMarkdown(source, options = {}) {
         hasMath: false,
         lang: options.lang ?? DEFAULT_LANG,
         hasTocMarker: false,
+        hyphenate: options.hyphenate,
     };
     const tokens = md.parse(source, env);
     let title;

package/dist/options.d.ts

@@ -43,6 +43,8 @@ export interface DocumentOptions {
     mermaidAutofit: boolean;
     /** Whether autofit may turn a flowchart to the other axis (LR ↔ TB) when it reads far better. */
     mermaidFlip: MermaidFlip;
+    /** Justify paragraphs in the PDF (body, quotes, alerts), breaking long words with hyphens. */
+    justify: boolean;
     /** Typeface of the text: Manrope or Inter (code is always JetBrains Mono). */
     font: TextFont;
     /** Vertical spacing: "compact" tightens line height, paragraph and heading spacing. */

package/dist/options.js

@@ -19,6 +19,7 @@ export const DEFAULT_OPTIONS = {
     mermaidAutofit: true,
     mermaidFlip: "auto",
     font: "manrope",
+    justify: true,
     density: "normal",
     theme: "light",
     css: [],
@@ -118,6 +119,7 @@ const VALIDATORS = {
     mermaidAutofit: bool,
     mermaidFlip: oneOf(MERMAID_FLIPS),
     font: oneOf(TEXT_FONTS),
+    justify: bool,
     density: oneOf(DENSITIES),
     fontSize,
     theme: (value, describe, baseDir) => {

package/dist/render/browser.d.ts

@@ -21,7 +21,20 @@ export interface PrintOptions {
     footerTemplate?: string;
     /** Let the page load http(s) resources (remote images, stylesheets). Off by default. */
     allowRemote?: boolean;
+    /**
+     * Width of the text column in CSS px. When set, the soft hyphens that do not fall at the end of
+     * a line are removed before printing (see SOFT_HYPHEN_CLEANUP).
+     */
+    softHyphensWidthPx?: number;
 }
+/**
+ * Keep only the soft hyphens (U+00AD) where a line actually breaks. Chrome copies every soft
+ * hyphen into the PDF's text, which splits words for copy, search and text extraction; only the
+ * ones that print as "-" belong there. The page is laid out at the printed column width with
+ * print styles; Chrome breaks lines greedily, so removing break points it did not use leaves
+ * every line as it was. Runs as our own code in the print page, whose scripts are disabled.
+ */
+export declare const SOFT_HYPHEN_CLEANUP = "(width) => {\n  const root = document.documentElement;\n  root.style.width = width + \"px\";\n  try {\n    const range = document.createRange();\n    // The character right after a used soft hyphen also reports the \"-\" drawn at the end of the\n    // previous line: take its last rectangle, and the first one for the character before.\n    const top = (node, i, last) => {\n      range.setStart(node, i);\n      range.setEnd(node, i + 1);\n      const rects = [...range.getClientRects()].filter((r) => r.width > 0);\n      const rect = last ? rects[rects.length - 1] : rects[0];\n      return rect ? rect.top : NaN;\n    };\n    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);\n    const nodes = [];\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      if (node.data.includes(\"\u00AD\")) nodes.push(node);\n    }\n    let kept = 0;\n    for (const node of nodes) {\n      const text = node.data;\n      let result = \"\";\n      for (let i = 0; i < text.length; i++) {\n        if (text[i] !== \"\u00AD\") {\n          result += text[i];\n        } else if (i > 0 && i < text.length - 1 && top(node, i + 1, true) > top(node, i - 1) + 1) {\n          result += text[i];\n          kept++;\n        }\n      }\n      node.data = result;\n    }\n    return kept;\n  } finally {\n    root.style.width = \"\";\n  }\n}";
 /** One headless browser shared by every step of a conversion (Mermaid, then PDF). */
 export declare class BrowserSession {
     private readonly browser;

package/dist/render/browser.js

@@ -22,6 +22,51 @@ export function shouldRetryWithoutSandbox(error, args, platform = process.platfo
         !args.includes("--no-sandbox") &&
         /no usable sandbox/i.test(String(error?.message ?? error)));
 }
+/**
+ * Keep only the soft hyphens (U+00AD) where a line actually breaks. Chrome copies every soft
+ * hyphen into the PDF's text, which splits words for copy, search and text extraction; only the
+ * ones that print as "-" belong there. The page is laid out at the printed column width with
+ * print styles; Chrome breaks lines greedily, so removing break points it did not use leaves
+ * every line as it was. Runs as our own code in the print page, whose scripts are disabled.
+ */
+export const SOFT_HYPHEN_CLEANUP = `(width) => {
+  const root = document.documentElement;
+  root.style.width = width + "px";
+  try {
+    const range = document.createRange();
+    // The character right after a used soft hyphen also reports the "-" drawn at the end of the
+    // previous line: take its last rectangle, and the first one for the character before.
+    const top = (node, i, last) => {
+      range.setStart(node, i);
+      range.setEnd(node, i + 1);
+      const rects = [...range.getClientRects()].filter((r) => r.width > 0);
+      const rect = last ? rects[rects.length - 1] : rects[0];
+      return rect ? rect.top : NaN;
+    };
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    const nodes = [];
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+      if (node.data.includes("\u00AD")) nodes.push(node);
+    }
+    let kept = 0;
+    for (const node of nodes) {
+      const text = node.data;
+      let result = "";
+      for (let i = 0; i < text.length; i++) {
+        if (text[i] !== "\u00AD") {
+          result += text[i];
+        } else if (i > 0 && i < text.length - 1 && top(node, i + 1, true) > top(node, i - 1) + 1) {
+          result += text[i];
+          kept++;
+        }
+      }
+      node.data = result;
+    }
+    return kept;
+  } finally {
+    root.style.width = "";
+  }
+}`;
 /**
  * Only allow requests the document needs: inline data, plus http(s) when `allowRemote`.
  * file: URLs are always refused, so HTML in a Markdown file cannot pull local files into
@@ -105,6 +150,11 @@ 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)");
+            if (options.softHyphensWidthPx !== undefined) {
+                await page.emulateMediaType("print");
+                await page.setViewport({ width: Math.ceil(options.softHyphensWidthPx), height: 1000 });
+                await page.evaluate(`(${SOFT_HYPHEN_CLEANUP})(${options.softHyphensWidthPx})`);
+            }
             const pdf = await page.pdf({
                 format: options.format ?? "A4",
                 landscape: options.landscape ?? false,

package/dist/render/page.d.ts

@@ -1,6 +1,11 @@
 import type { PageSize } from "../options.js";
 export declare function lengthToPx(length: string): number;
-/** Width of the text column in CSS pixels, so diagrams are laid out at their printed size. */
+/** Exact width of the text column in CSS pixels, as Chrome prints it. */
+export declare function textWidthPx(pageSize: PageSize, landscape: boolean, margin: {
+    left: string;
+    right: string;
+}): number;
+/** Width of the text column in whole CSS pixels, so diagrams are laid out at their printed size. */
 export declare function contentWidthPx(pageSize: PageSize, landscape: boolean, margin: {
     left: string;
     right: string;

package/dist/render/page.js

@@ -14,11 +14,15 @@ export function lengthToPx(length) {
         throw new Error(`invalid length: ${length}`);
     return Number(match[1]) * PX_PER_UNIT[match[2]];
 }
-/** Width of the text column in CSS pixels, so diagrams are laid out at their printed size. */
-export function contentWidthPx(pageSize, landscape, margin) {
+/** Exact width of the text column in CSS pixels, as Chrome prints it. */
+export function textWidthPx(pageSize, landscape, margin) {
     const [width, height] = PAPER_MM[pageSize];
     const paperPx = ((landscape ? height : width) * 96) / 25.4;
-    return Math.round(paperPx - lengthToPx(margin.left) - lengthToPx(margin.right));
+    return paperPx - lengthToPx(margin.left) - lengthToPx(margin.right);
+}
+/** Width of the text column in whole CSS pixels, so diagrams are laid out at their printed size. */
+export function contentWidthPx(pageSize, landscape, margin) {
+    return Math.round(textWidthPx(pageSize, landscape, margin));
 }
 /** Height of the text area in CSS pixels: the paper minus the top and bottom margins. */
 export function contentHeightPx(pageSize, landscape, margin) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imontene/mdrender",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Command-line app for Windows and Linux that renders Markdown — with LaTeX equations and Mermaid diagrams — to PDF and HTML set in Manrope or Inter",
   "keywords": [
     "markdown",
@@ -71,6 +71,7 @@
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
     "highlight.js": "^11.12.0",
+    "hyphen": "^1.14.1",
     "inter-ui": "^4.1.1",
     "katex": "^0.19.0",
     "markdown-it": "^15.0.2",
@@ -83,6 +84,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@types/hyphen": "^1.14.0",
     "@types/node": "^22.20.5",
     "@vitest/coverage-v8": "^5.0.3",
     "esbuild": "^0.28.2",