Source plugins API

Fetching your site sources

Info

Please make sure to check out Source 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 Source plugin

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

interface ISourcePlugin {
  sourceFiles(args: sourceFilesArgs): Promise<VFile[]>;
}

e.g. it exports a sourceFiles() method which returns a Promise resolving an Array of Virtual Files.

Here is an naive example of a source plugin retrieving 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 limedocs.config.js:

module.exports = {
  // ...
  sources: [
    {
      // Plugin filename or npm-package name if you published one!
      resolve: "path/to/simple-sql-source-plugin.js",
      // Plugin options passed to your sourceFiles() method
      options: {
        table: "my_table"
      }
    }
  ]
  // ...
}

Edit this page / submit change