Skip to content

Source

Jump to bottom
Victor edited this page Jan 9, 2020 · 1 revision

Format

Definition

Source, you can pass to library, is defined as

// file url
export type FileURI = string // -> "file://..."

// single source
export type PlainSource =
  | string                // -> plain text (HTML, Markdown, TXT and so on)
  | Buffer                // -> Buffer
  | FileURI               // -> FileURI
  | NodeJS.ReadableStream // -> or NodeJS.ReadableStream

// tuple
export type TupleSource = [string, PlainSource] // -> [filename, PlainSource]

// object
export type ObjectSource = { [name: string]: PlainSource } // -> { [filename]: PlainSource }

// source
export type Source =
  | URL           // -> single URL (for URL conversion)
  | PlainSource   // -> any PlainSource
  | TupleSource   // -> any TupleSource
  | ObjectSource  // -> any ObjectSource
  | Array<PlainSource | TupleSource | ObjectSource> // -> array with PlainSources, TupleSources or ObjectSources
  | Iterable<PlainSource | TupleSource | ObjectSource> // -> any iterable with PlainSources, TupleSources or ObjectSources

Examples

You are free to chose any format you like/need (I use html files just for example, but this applies for any asset types):

// string
const pdf = await toPDF('<html>...</html>')

// Buffer
const pdf = await toPDF(fs.readFileSync('index.html'))

// FileURI
const pdf = await toPDF('file://index.html')

// NodeJS.ReadableStream
const pdf = await toPDF(fs.createReadStream('index.html'))

// tuple with string
const pdf = await toPDF(['index.html', '<html>...</html>'])

// tuple with Buffer
const pdf = await toPDF(['index.html', fs.readFileSync('index.html')])

// tuple with FileURI
const pdf = await toPDF(['index.html', 'file://index.html'])

// tuple with NodeJS.ReadableStream
const pdf = await toPDF(['index.html', fs.createReadStream('index.html')])

// object with Buffer
const pdf = await toPDF({ 'index.html': fs.readFileSync('index.html') })

// object with different PlainSource
const pdf = await toPDF({
  'index.html': '<html>...</html>',
  'header.html': 'file://header.html',
  'footer.html': fs.readFileSync('footer.html'),
})

// array with tuples
const pdf = await toPDF([
  ['index.html', '<html>...</html>'],
  ['header.html', 'file://header.html'],
  ['footer.html', fs.readFileSync('footer.html')],
])

// mixed array with tuples and objects
const pdf = await toPDF([
  ['index.html', '<html>...</html>'],
  {
    'header.html': 'file://header.html',
    'footer.html': fs.readFileSync('footer.html'),
  },
])

Instead of array you can use any iterable object, like Map, Set, arguments and so on.

You can even use some exotic variants, like generators:

function* getSources() {
  yield ['index.html', '<html>...</html>']
  yield ['header.html', 'file://header.html']
  yield ['footer.html', fs.readFileSync('footer.html')]
}

const pdf = await toPDF(getSources())

File names

Each asset in Gotenberg must have a name.

As not any source format has file name, library will try to guess file name:

  • for plain string and Buffer, filename will be index.html
  • for FileURI, filename will be retrieved from uri
  • for fs.ReadStream, filename will be retrieved from file stream

Any time, when library cannot determine asset filename - default name index.html is used.

This could cause some issues, for example, if you want to convert Office documents, see issue #5. In case of any doubts you can specify filename directly, using tuples or object as a source.

Clone this wiki locally