Diagnostics

Pardown reports recoverable conversion problems through onDiagnostic. This reference explains the default behaviour, both diagnostic variants, collection patterns, and errors that still reject conversion.

Receive diagnostics

Pass a DiagnosticHandler as onDiagnostic to collect or report warnings. Pardown calls the handler while preparing the document.

import { markdownToPdf, type Diagnostic } from '@pardown/core';

const diagnostics: Diagnostic[] = [];
const pdf = await markdownToPdf('![Missing chart](charts/missing.png)', {
  onDiagnostic: (diagnostic) => diagnostics.push(diagnostic),
});

for (const diagnostic of diagnostics) {
  console.warn(diagnostic.code, diagnostic.message);
}

The generated PDF remains the return value. Diagnostics aren't included in a result object.

Use the default handler

defaultDiagnosticHandler calls console.warn with each diagnostic's message. Pardown uses it when you omit onDiagnostic.

import { defaultDiagnosticHandler, markdownToPdf } from '@pardown/core';

const markdown = '# Stock report';
const pdf = await markdownToPdf(markdown, {
  onDiagnostic: defaultDiagnosticHandler,
});

Set onDiagnostic to an empty function when you intentionally want to suppress recoverable warnings:

import { markdownToPdf } from '@pardown/core';

const markdown = '# Stock report';
const pdf = await markdownToPdf(markdown, {
  onDiagnostic: () => {},
});

Image load failures

Pardown emits IMAGE_LOAD_FAILED when it can't fetch, read, or decode an image. The diagnostic includes the original source and underlying cause.

type ImageLoadFailedDiagnostic = {
  level: 'warning';
  code: 'IMAGE_LOAD_FAILED';
  message: string;
  source: string;
  cause: unknown;
};

Pardown omits the failed image and renders its alternative text instead. If an image load fails after the supplied abort signal is aborted, conversion rejects rather than emitting this diagnostic.

Unsupported nodes

Pardown emits UNSUPPORTED_NODE when the parsed document contains an element without a dedicated renderer. The diagnostic identifies the unsupported node type.

type UnsupportedNodeDiagnostic = {
  level: 'warning';
  code: 'UNSUPPORTED_NODE';
  message: string;
  nodeType: string;
};

Pardown removes the unsupported wrapper and recursively renders supported descendants. Read Unsupported elements for common examples and layout implications.

Handle each diagnostic type

Use the code property to narrow the Diagnostic union and access variant-specific fields.

import type { DiagnosticHandler } from '@pardown/core';

const onDiagnostic: DiagnosticHandler = (diagnostic) => {
  switch (diagnostic.code) {
    case 'IMAGE_LOAD_FAILED':
      console.warn(`Couldn't load ${diagnostic.source}`, diagnostic.cause);
      break;
    case 'UNSUPPORTED_NODE':
      console.warn(`Unsupported element: ${diagnostic.nodeType}`);
      break;
  }
};

Both current variants have level: 'warning'. Use code, rather than the level, when your application needs variant-specific behaviour.

Understand fatal errors

Diagnostics only cover recoverable image and node problems. markdownToPdf still rejects when parsing or PDF rendering fails, an aborted image load is rethrown, or your custom image loader or diagnostic handler throws.

Handle the conversion promise separately from the diagnostic callback:

import { writeFile } from 'node:fs/promises';
import { markdownToPdf } from '@pardown/core';

const markdown = '# Stock report';

try {
  const pdf = await markdownToPdf(markdown, {
    onDiagnostic: (diagnostic) => console.warn(diagnostic.message),
  });
  await writeFile('stock-report.pdf', pdf);
} catch (error) {
  console.error('PDF conversion failed', error);
}

The catch block covers fatal conversion and file-writing errors. Recoverable diagnostics still reach onDiagnostic.

API types

The public diagnostic API consists of the union, its variants, and the handler type.

type Diagnostic = ImageLoadFailedDiagnostic | UnsupportedNodeDiagnostic;
type DiagnosticHandler = (diagnostic: Diagnostic) => void;

Read the @pardown/core API reference for all signatures and public exports.