Transformation plugins API

Transforming files content

Info

Please make sure to check out Transformation Plugins intro before reading this.

About writing plugins

There are two ways of writing a plugin: Using an ES6 class (or ES5 function) which will be instanciated by Limedocs, or simply by exporting needed methods. For the sake of simplicity, we will use the second option for the following examples.

Anatomy of a Transformation plugin

A transform plugin must comply with the following pseudo-interface:

interface TransformPlugin {
  get inputContentType(): string | string[],
  get outputContentType(): string,
  transform(file: VFile):  VFile | VFile[] | null
}
  • inputContentType(): returns a Content-Type (or an Array of Content-Types) that the plugin is capable of handling.
  • outputContentType(): returns the Content-type the plugin will transform virtual-files into.
  • transform(): takes a virtual file and return it after having it transformed.

Here is an naive example of a transform plugin converting wiki-formated files to HTML files:

// A dummy example using a fake "my-wiki-converter"
import { convert } from "my-wiki-converter"

export default class MyWikiTransformer {

  // declare the content-type the plugin can process
  get inputContentType() {
    return "text/wiki-format"
  }

  // declare the content-type the plugin will output
  get outputContentType() {
    return "text/html"
  }

  // transform VFiles (generaly from one content-type to another)
  transform(file) {
    const newContent = convert(file.contents)
    file.contents = newContent      // sets new content
    // Limedocs will automatically set `file.contentType` to "text/wiki-format" (inputContentType value)
    return file
  }

}
// A dummy example using a fake "my-wiki-converter"
import { convert } from "my-wiki-converter"

// declare the content-type the plugin can process
export const inputContentType = "text/wiki-format"

// declare the content-type the plugin will output
export const outputContentType = "text/html"

// transform VFiles (generaly from one content-type to another)
export function transform(file) {
  const newContent = convert(file.contents)
  file.contents = newContent      // sets new content
  // Limedocs will automatically set `file.contentType` to "text/wiki-format" (inputContentType value)
  return file
}

Transformation possibilities

Converting a file

This is the common usage: your transform() method takes a VFile, transform it and return it. Usually you will touch its contents property and possibly its contentType.

Transforming a file to several new files

You may want to generate new files from existing ones. Here is how you can do: let's say you have a text file containing one employee name by line and you'd like to generate one page per employee:

John Doe
Jane Doe
Pierre Richard
...

To generate new files, your transform() method will have to return an array of VFiles.

import { vfile } from "@limedocs/core"

// declare the content-type the plugin can process
export const inputContentType = "text/plain"

// declare the content-type the plugin will output
export const outputContentType = "text/plain"

// Return a new array of VFiles
export function transform(file: VFile) {
  // file.contents is a Buffer, transform it to a string
  const contents = file.contents.toString() 
  return contents.split("\n").map((employee, index) => 
    vfile({
      path: `${file.dirname}/page-${index}.txt`,
      contents: Buffer.from(`Page of: ${employee}`, "utf8")
    })
  )
}
Warning

In the previous example, returning new files will discard/remove the previous file (employees.txt). If you want to keep this file in your site, return it in the array as well.

Discarding a file

To discard a vfile, simply return null in your transform() method.

// Returning null to discard a specific file
export function transform(file: VFile) {
  if (file.path === "path/specific") {
    return  null
  }
  return file
}

Asynchronous transformation

If you need async transformation, just return a Promise which will resolve to a VFile, VFile[], or null.

// Return a promise
export function transform(file: VFile) {
  return new Promise((resolve, reject) => {
    // process file
    // ....
    // then resolve
    resolve(file)
  })
}

Edit this page / submit change