@pardown/core API

@pardown/core exposes one conversion function, default handlers and settings, and their TypeScript types. This page documents the complete public package entry point.

markdownToPdf

markdownToPdf parses a Markdown string, loads its images, renders one PDF document, and resolves with the complete PDF bytes.

function markdownToPdf(
  markdown: string,
  options?: MarkdownToPdfOptions,
): Promise<Uint8Array<ArrayBuffer>>;

The markdown argument must be a string. Pardown doesn't accept a stream, file path, DOM tree, or Comark abstract syntax tree through its public package entry point.

A minimal conversion looks like this:

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

const pdf = await markdownToPdf('# Equipment register');

MarkdownToPdfOptions

The optional second argument controls image loading, diagnostics, and image-load cancellation.

type MarkdownToPdfOptions = {
  cwd?: string;
  imageLoader?: ImageLoader;
  onDiagnostic?: DiagnosticHandler;
  signal?: AbortSignal;
};

Each property has the following behaviour:

• cwd sets the base directory passed to image loading. The default image loader joins it to local image sources.
• imageLoader replaces defaultImageLoader.
• onDiagnostic replaces defaultDiagnosticHandler.
• signal is passed to image loading and can abort an in-progress load.

All properties are optional. Pardown currently has no public theme option.

Image loading API

The image loading API lets you replace file and network access while keeping image discovery and PDF rendering inside Pardown.

ImageLoader

An ImageLoader receives the source exactly as it appears in the parsed image node and returns the image's raw bytes.

type ImageLoader = (
  source: string,
  context: ImageLoaderContext,
) => Promise<Uint8Array>;

Pardown de-duplicates exact source strings, calls the loader once for each unique source, and loads distinct sources concurrently.

ImageLoaderContext

The loader context contains the values that can affect resource access.

type ImageLoaderContext = {
  cwd?: string;
  signal?: AbortSignal;
};

A custom loader decides how to interpret cwd. It must forward signal to its underlying operation if you want cancellation to take effect.

defaultImageLoader

defaultImageLoader supports HTTP, HTTPS, and local file sources.

const defaultImageLoader: ImageLoader;

For a valid http: or https: URL, it calls fetch and rejects a response outside the successful range. For every other source, it dynamically imports node:fs/promises and node:path, joins cwd to the source when cwd is present, and reads the file.

IMPORTANT

The local-file branch requires a Node.js-compatible environment. Provide a custom imageLoader for relative browser resources.

Read Image loading and cancellation for practical loader examples and abort behaviour.

Diagnostic API

Diagnostics report recoverable rendering problems. Both current diagnostic variants have the warning level. Read Diagnostics for collection and error-handling patterns.

Diagnostic

Diagnostic is a discriminated union of the diagnostic variants.

type Diagnostic = ImageLoadFailedDiagnostic | UnsupportedNodeDiagnostic;

Use the code property to narrow the union in TypeScript.

ImageLoadFailedDiagnostic

Pardown emits IMAGE_LOAD_FAILED when an image can't be fetched, read, or decoded.

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

Pardown omits the failed image and renders its alternative text. When an abort signal is already aborted, Pardown rejects the conversion instead of emitting this diagnostic.

UnsupportedNodeDiagnostic

Pardown emits UNSUPPORTED_NODE when no mapper exists for a parsed node.

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

Pardown removes the unsupported wrapper and recursively renders its supported descendants.

DiagnosticHandler

A diagnostic handler receives each diagnostic synchronously while Pardown prepares the document.

type DiagnosticHandler = (diagnostic: Diagnostic) => void;

If the handler throws, markdownToPdf rejects with that error.

defaultDiagnosticHandler

defaultDiagnosticHandler writes each diagnostic's message with console.warn.

const defaultDiagnosticHandler: DiagnosticHandler;

Set onDiagnostic to an empty function if you intentionally want to suppress recoverable warnings.

Theme exports

Pardown exposes its current theme value and type for inspection. The conversion API doesn't yet let you supply a different theme.

defaultTheme

defaultTheme contains the settings used for every conversion.

const defaultTheme: PardownTheme;

Notable defaults include an A4 page with a 56-point margin, 11-point body text, a centred level 1 heading, syntax-highlighted code blocks, underlined links, and full-width images.

PardownTheme

PardownTheme describes settings for the Jasy document, page, headings, paragraphs, lists, code blocks, dividers, inline styles, and images.

The public type has the following shape. This declaration excerpt is for reference; import PardownTheme from @pardown/core rather than copying it.

import type {
  BoxOptions,
  DividerOptions,
  DocumentOptions,
  ImageOptions,
  Insets,
  PageOptions,
  TextOptions,
} from '@jasy/pdf';

type ThemeTextStyle = {
  fontSize?: number;
  fontFamily?: string;
  color?: string;
  underline?: boolean;
  bold?: boolean;
  strikethrough?: boolean;
  italic?: boolean;
};

type HeadingTheme = {
  padding: Insets;
  textStyle: ThemeTextStyle;
  textOptions: TextOptions;
};

type PardownTheme = {
  document: DocumentOptions;
  page: PageOptions;
  paragraph: {
    padding: Insets;
    textOptions: TextOptions;
  };
  headings: {
    h1: HeadingTheme;
    h2: HeadingTheme;
    h3: HeadingTheme;
  };
  list: {
    spacing: BoxOptions;
    itemPadding: Insets;
    marker: BoxOptions;
  };
  codeBlock: {
    box: BoxOptions;
    textStyle: ThemeTextStyle;
  };
  divider: DividerOptions;
  inline: {
    strong: ThemeTextStyle;
    emphasis: ThemeTextStyle;
    deletion: ThemeTextStyle;
    code: ThemeTextStyle;
    link: ThemeTextStyle;
  };
  image: {
    padding: Insets;
    options: Omit<ImageOptions, 'alt'>;
    fallbackText: TextOptions;
  };
};

HeadingTheme and ThemeTextStyle are internal names used within the public shape but aren't separate package exports. The generated declaration includes their structure, so TypeScript can still resolve PardownTheme correctly.

NOTE

Changing or copying defaultTheme doesn't affect markdownToPdf. Pardown currently always uses the original built-in theme.

Public exports

The package entry point contains only the following supported exports. Importing internal source paths isn't part of the public API.

Runtime exports:

• markdownToPdf
• defaultImageLoader
• defaultDiagnosticHandler
• defaultTheme

Type exports:

• MarkdownToPdfOptions
• ImageLoader
• ImageLoaderContext
• Diagnostic
• DiagnosticHandler
• ImageLoadFailedDiagnostic
• UnsupportedNodeDiagnostic
• PardownTheme

Although the source contains an astToPdf function, @pardown/core doesn't export it. Use markdownToPdf as the supported conversion entry point.