Plugins

Note

Please make sure to read Limedocs Concepts first to understand the mean of plugins.

There are 3 types of plugins in limedocs: source plugins, transform plugins, and output-plugins.

Source plugins

These plugins allows you to pull your website sources. Usually you will use @limedocs/source-filesystem plugin to generate documentation from markdown files, but you could also want to develop source plugins to pull data from a database, http requests, etc. Multiple sources plugins can be used at the same time.

A source plugin exports a sourceFiles() method which returns a Promise resolving an array of virtual files (vfile).

Here is an naive example of a source plugin retreiving content from a database:

import { vfile } from "@limedocs/core"

// sourceFiles takes one argument: an options object
exports.sourceFiles = (options) => {
  // fake `query` function returning a Promise
  return query(`SELECT * FROM ${options.table}`)
    // `documents` is an array of table rows
    .then(documents => {
      // to create a vfile, you have to provide a few keys:
      //   - path: path uniquely identifying the file (mandatory)
      //   - contents: file contents (Buffer or string) (mandatory)
      //   - data: Object holding metadata (optional)
      // Here we map all documents to vfiles
      return documents.map(doc => vfile({path: doc.path, contents: doc.text}))
    })
}

And that's it, we got our sources!

To use your new source plugin, simply reference it in your config:

sources:
- resolve: limedocs-source-query # package name or path to your js file
  options:
    table: my_table

Transform plugins

Now that we have sources (virtual files), we may want to transform them, and that's the job of transform plugins.

A transform plugin exports 3 methods:

  • inputContentType(): returns a content-type (or an array of content-types) the plugin is capable of handling.
  • outputContentType(): returns the content-type the plugin will transform vfiles 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"

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

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

// transform VFiles (generaly from one content-type to another)
export function transform(file: vfile) {
  const newContent = convert(file.contents)
  file.contents = newContent      // sets new content
  file.contentType = "text/html"  // sets new content type, it's mandatory !
  return file
}
  • Transform plugins
  • Output plugins

Edit this page / submit change