Docs

Node Client

A Node.js client for the MarkupGo API.

Node client for the MarkupGo API.

It provides methods to generate images and PDFs from templates, URLs, or HTML. It also supports converting over 130 document formats to PDF, including .docx, .xlsx, .pptx, and more.

Installation

To install the library, use npm or yarn:

npm install markupgo-node

or

yarn add markupgo-node

Initialization

To use MarkupGo, you need to initialize it with your API key:

import MarkupGo from "markupgo-node";

const markupgo = new MarkupGo({
  API_KEY: "your_api_key_here",
});

Overview of Classes

  • ImageConversion
    • Provides methods to generate images from templates, URLs, or HTML strings.
  • PdfConversion
    • Provides methods to generate PDFs from templates, URLs, or HTML strings.
  • OfficeConversion
    • Provides methods to convert over 130 document formats to PDF, including .docx, .xlsx, .pptx, and more. It supports merging multiple files into a single PDF.

Response Types

  • ITask
    • Represents the task details and includes information such as ID, URL, format, size, width, and height.
  • Buffer
    • Used to handle raw binary data for image or PDF output.

Image Conversion Methods

The Image Conversion API enables the generation of images from templates, URLs, or HTML strings. It supports various image formats, including PNG, JPEG, and WebP, and provides options to customize the output.

Please refer to the Image API documentation for more information.

fromTemplate

import * as fs from "fs";

const templateData: TemplateData = {
  id: PODCAST_TEMPLATE_ID,
  context: { 
    title: 'Episode 1',
    description: 'We talk about stuff and things, tune in!'
  }
};

const imageOptions: ImageOptions = {
  properties: {
    format: "png",
    width: 800,
    height: 600,
  }
};

markupgo.image.fromTemplate(templateData, imageOptions).json()
.then((task) => {
  console.log(task);
});

markupgo.image.fromTemplate(templateData, imageOptions).buffer()
.then((buffer) => {
  fs.writeFileSync("output.png", Buffer.from(buffer));
});

fromUrl

import * as fs from "fs";

const url: string = "https://example.com";

const imageOptions: ImageOptions = {
 properties: {
    format: "jpeg",
    width: 800,
    height: 600,
    clip: true,
  }
};

markupgo.image.fromUrl(url, imageOptions).json()
.then((task) => {
  console.log(task);
});

markupgo.image.fromUrl(url, imageOptions).buffer()
.then((buffer) => {
  fs.writeFileSync("output.jpg", Buffer.from(buffer));
});

Heads up!

For the URL source (fromUrl method), the clip option will clip the image to the specified width and height. If false, the height will be ignored. For other conversion types, you don't need to set the clip option to force the image to be clipped.

fromHtml

import * as fs from "fs";

const html: string = "<html><body>Hello World</body></html>";

const imageOptions: ImageOptions = {
  properties: {
    format: "webp",
    width: 800,
    height: 600,
  }
};

markupgo.image.fromHtml(html, imageOptions).json()
.then((task) => {
  console.log(task);
});

markupgo.image.fromHtml(html, imageOptions).buffer()
.then((buffer) => {
  fs.writeFileSync("output.webp", Buffer.from(buffer));
});

fromMarkdown

import * as fs from "fs";

const input: MarkdownInput = {
  markdown: "# Hello World",
  css: "h1 { color: #f2f2f2; }",
  dark: true,
  padding: 45,
}

const imageOptions: ImageOptions = {
  properties: {
    format: "png",
    width: 800,
    height: 600,
  }
};

markupgo.image.fromMarkdown(input, imageOptions).json()
.then((task) => {
  console.log(task);
});

markupgo.image.fromMarkdown(input, imageOptions).buffer()
.then((buffer) => {
  fs.writeFileSync("output.png", Buffer.from(buffer));
});

PDF Conversion Methods

Generate PDFs from URLs, HTML, and templates. Please refer to the PDF API documentation for more information.

fromTemplate

import * as fs from "fs";

const templateData: TemplateData = {
  id: PODCAST_TEMPLATE_ID,
  context: { 
    title: 'Episode 1',
    description: 'We talk about stuff and things, tune in!'
  }
};

const pdfOptions: PdfOptions = {
  properties: {
    printBackground: true,
    landscape: true,
  },
};

markupgo.pdf.fromTemplate(templateData, pdfOptions).json()
.then((task) => {
  console.log(task);
});

markupgo.pdf.fromTemplate(templateData, pdfOptions).buffer()
.then((buffer) => {
  fs.writeFileSync("output.pdf", Buffer.from(buffer));
});

fromUrl

import * as fs from "fs";

const url: string = "https://example.com";

const pdfOptions: PdfOptions = {
  properties: {
    printBackground: true,
    landscape: true,
  },
};

markupgo.pdf.fromUrl(url, pdfOptions).json()
.then((task) => {
  console.log(task);
});

markupgo.pdf.fromUrl(url, pdfOptions).buffer()
.then((buffer) => {
  fs.writeFileSync("output.pdf", Buffer.from(buffer));
});

fromHtml

import * as fs from "fs";

const html: string = "<html><body>Hello World</body></html>";

const pdfOptions: PdfOptions = {
  properties: {
    printBackground: true,
    landscape: true,
  },
};

markupgo.pdf.fromHtml(html, pdfOptions).json()
.then((task) => {
  console.log(task);
});

markupgo.pdf.fromHtml(html, pdfOptions).buffer()
.then((buffer) => {
  fs.writeFileSync("output.pdf", Buffer.from(buffer));
});

fromMarkdown

import * as fs from "fs";

const input: MarkdownInput = {
  markdown: "# Hello World",
  css: "h1 { color: #f2f2f2; }",
  dark: true,
  padding: 45,
}

const pdfOptions: PdfOptions = {
  properties: {
    singlePage: true, // Best way to render all content in a single page
  },
};

markupgo.pdf.fromMarkdown(input, pdfOptions).json()
.then((task) => {
  console.log(task);
});

markupgo.pdf.fromMarkdown(input, pdfOptions).buffer()
.then((buffer) => {
  fs.writeFileSync("output.pdf", Buffer.from(buffer));
});

Office to PDF Conversion

The Office to PDF API enables seamless conversion of over 130 document formats to PDF, including .docx, .xlsx, .pptx, and more. Whether you need high-quality conversions, custom PDF properties, or to merge multiple files, this API simplifies the process.

Please refer to the Office to PDF API documentation for more information for supported formats, options, limits, and more.

Examples

Convert a .docx File to PDF

import { type PathLikeOrReadStream } from "markupgo-node";
import fs from "fs";

const buffer = fs.readFileSync("./src/playground/test.docx");

const files = [
  {
    data: buffer,
    ext: "csv",
  },
  "./src/playground/report.xlsx",
] as PathLikeOrReadStream[];

markupgo.office.convert(files).json().then((task) => {
  console.log(task);
});

// OR
markupgo.office.convert(files).buffer().then((buffer) => {
  fs.writeFileSync("output.pdf", Buffer.from(buffer));
});

Convert Multiple Files to PDF with Merging

The merge option must be set to true to merge multiple files into a single PDF.

import { type PathLikeOrReadStream } from "markupgo-node";
import fs from "fs";

const buffer = fs.readFileSync("./src/playground/test.docx");

const files = [
  {
    data: buffer,
    ext: "csv",
  },
  "./src/playground/report.xlsx",
] as PathLikeOrReadStream[];

const options: OfficeToPdfOptions = {
  merge: true,
};

markupgo.office.convert(files, options).json().then((task) => {
  console.log(task);
});
// OR
markupgo.office.convert(files, options).buffer().then((buffer) => {
  fs.writeFileSync("output.pdf", Buffer.from(buffer));
});

Convert a .docx File to PDF with Custom Options

import { type PathLikeOrReadStream } from "markupgo-node";
import fs from "fs";

const buffer = fs.readFileSync("./src/playground/test.docx");

const files = [
  {
    data: buffer,
    ext: "csv",
  },
  "./src/playground/report.xlsx",
] as PathLikeOrReadStream[];

const options: OfficeToPdfOptions = {
  properties: {
    landscape: true,
    printBackground: true,
  }
};

markupgo.office.convert(files, options).json().then((task) => {
  console.log(task);
});
// OR
markupgo.office.convert(files, options).buffer().then((buffer) => {
  fs.writeFileSync("output.pdf", Buffer.from(buffer));
});

Types

Image

Common Types
type ImageProperties = {
  format?: 'png' | 'jpeg' | 'webp';
  quality?: number;
  omitBackground?: boolean;
  width?: number;
  height?: number;
  clip?: boolean;
}

type ImageOptions = {
  properties?: ImageProperties;
  emulatedMediaType?: 'screen' | 'print';
  waitDelay?: string;
  waitForExpression?: string;
  extraHttpHeaders?: Record<string, string>;
  failOnConsoleExceptions?: boolean;
  failOnHttpStatusCodes?: number[];
  skipNetworkIdleEvent?: boolean;
  optimizeForSpeed?: boolean;
}

type ITask = {
  id: string;
  url: string;
  format: 'png' | 'jpeg' | 'webp'
  size: number;
  width: number;
  height: number;
}
fromTemplate
fromTemplate(data: TemplateData, options?: ImageOptions): {
  json: () => Promise<ITask>;
  buffer: () => Promise<ArrayBuffer>;
}

type TemplateData = {
  id: string;
  context?: Record<string, any>;
  html?: string;
  css?: string;
  libraries?: Record<string, string>[];
  autoHeight?: boolean;
}
fromUrl
fromUrl(url: string, options?: ImageOptions): {
  json: () => Promise<ITask>;
  buffer: () => Promise<ArrayBuffer>;
}
fromHtml
fromHtml(html: string, options?: ImageOptions): {
  json: () => Promise<ITask>;
  buffer: () => Promise<ArrayBuffer>;
}
fromMarkdown
fromMarkdown(input: MarkdownInput, options?: ImageOptions): {
  json: () => Promise<ITask>;
  buffer: () => Promise<ArrayBuffer>;
}

type MarkdownInput = {
  markdown: string;
  css?: string;
  dark?: boolean;
  padding?: number;
}

Pdf

Common Types
type PdfProperties = {
  singlePage?: boolean;
  size?: Size;
  margins?: Margins;
  preferCssPageSize?: boolean;
  printBackground?: boolean;
  omitBackground?: boolean;
  landscape?: boolean;
  scale?: number;
  nativePageRanges?: {
    from: number;
    to: number;
  };
}

type PdfOptions = {
  header?: string;
  footer?: string;
  properties?: PdfProperties;
  pdfUA?: boolean;
  emulatedMediaType?: 'screen' | 'print';
  waitDelay?: string;
  waitForExpression?: string;
  userAgent?: string;
  extraHttpHeaders?: Record<string, string>;
  failOnHttpStatusCodes?: number[];
  failOnConsoleExceptions?: boolean;
  skipNetworkIdleEvent?: boolean;
  metadata?: Record<string, string>;
  cookies?: Cookie[];
}

type Cookie = {
  name: string;
  value: string;
  domain: string;
  path?: string;
  secure?: boolean;
  httpOnly?: boolean;
  sameSite?: 'Strict' | 'Lax' | 'None';
}

type Size = {
  width?: number;
  height?: number;
}

type Margins = {
  top: number;
  bottom: number;
  left: number;
  right: number;
}
fromTemplate ```typescript fromTemplate(data: TemplateData, options?: PdfOptions): { json: () => Promise; buffer: () => Promise; }

type TemplateData = { id: string; context?: Record<string, any>; html?: string; css?: string; libraries?: Record<string, string>; }

</details>

<details>
<summary>fromUrl</summary>

```typescript
fromUrl(url: string, options?: PdfOptions): {
  json: () => Promise<ITask>;
  buffer: () => Promise<ArrayBuffer>;
}
fromHtml
fromHtml(html: string, options?: PdfOptions): {
  json: () => Promise<ITask>;
  buffer: () => Promise<ArrayBuffer>;
}
fromMarkdown
fromMarkdown(input: MarkdownOptions, options?: PdfOptions): {
  json: () => Promise<ITask>;
  buffer: () => Promise<ArrayBuffer>;
}

type MarkdownOptions = {
  markdown: string;
  css?: string;
  dark?: boolean;
  padding?: number;
}

Office to PDF

Common Types
type OfficeProperties = {
  landscape?: boolean;
  nativePageRanges?: {
    from: number;
    to: number;
  };
  exportFormFields?: boolean;
  singlePageSheets?: boolean;
  allowDuplicateFieldNames?: boolean;
  exportBookmarks?: boolean;
  exportBookmarksToPdfDestination?: boolean;
  exportPlaceholders?: boolean;
  exportNotes?: boolean;
  exportNotesPages?: boolean;
  exportOnlyNotesPages?: boolean;
  exportNotesInMargin?: boolean;
  convertOooTargetToPdfTarget?: boolean;
  exportLinksRelativeFsys?: boolean;
  exportHiddenSlides?: boolean;
  skipEmptyPages?: boolean;
  addOriginalDocumentAsStream?: boolean;
}

type OfficeToPdfOptions = {
  properties?: OfficeProperties;
  pdfUA?: boolean;
  merge?: boolean;
  metadata?: any;
  losslessImageCompression?: boolean;
  reduceImageResolution?: boolean;
  quality?: number;
  maxImageResolution?: 75 | 150 | 300 | 600 | 1200;
}
convert
convert(files: PathLikeOrReadStream[], options?: OfficeToPdfOptions): {
  json: () => Promise<ITask>;
  buffer: () => Promise<ArrayBuffer>;
}

type PathLikeOrReadStream = string | FileInfo;

type FileInfo = {
  data: Buffer | ReadStream;
  ext: FileExtension;
}

type FileExtension = '123' | '602' | 'abw' | 'bib' | 'bmp' | 'cdr' | 'cgm' | 'cmx' | 'csv' | 'cwk' | 'dbf' | 'dif' | 'doc' | 'docm' | 'docx' | 'dot' | 'dotm' | 'dotx' | 'dxf' | 'emf' | 'eps' | 'epub' | 'fodg' | 'fodp' | 'fods' | 'fodt' | 'fopd' | 'gif' | 'htm' | 'html' | 'hwp' | 'jpeg' | 'jpg' | 'key' | 'ltx' | 'lwp' | 'mcw' | 'met' | 'mml' | 'mw' | 'numbers' | 'odd' | 'odg' | 'odm' | 'odp' | 'ods' | 'odt' | 'otg' | 'oth' | 'otp' | 'ots' | 'ott' | 'pages' | 'pbm' | 'pcd' | 'pct' | 'pcx' | 'pdb' | 'pdf' | 'pgm' | 'png' | 'pot' | 'potm' | 'potx' | 'ppm' | 'pps' | 'ppt' | 'pptm' | 'pptx' | 'psd' | 'psw' | 'pub' | 'pwp' | 'pxl' | 'ras' | 'rtf' | 'sda' | 'sdc' | 'sdd' | 'sdp' | 'sdw' | 'sgl' | 'slk' | 'smf' | 'stc' | 'std' | 'sti' | 'stw' | 'svg' | 'svm' | 'swf' | 'sxc' | 'sxd' | 'sxg' | 'sxi' | 'sxm' | 'sxw' | 'tga' | 'tif' | 'tiff' | 'txt' | 'uof' | 'uop' | 'uos' | 'uot' | 'vdx' | 'vor' | 'vsd

Image Transformation

The Image Transformation API allows you to transform images on-the-fly. You can resize, crop, rotate, and apply various filters to images. The API is designed to be simple and easy to use, and it is optimized for performance.

Magic Template URL

Create Image & PDF from URL using your existing Template without any code using Magic URL