---
title: "Source plugins"
---

# Source plugins API

{% subtitle %}

Fetching your site sources

{% endsubtitle %}

{% alert type="info" %}

Please make sure to check out [Source Plugins intro](usage/pipeline-plugins.md#source-plugins) before reading this.

{% endalert %}

{% alert type="note" title="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.

{% endalert %}

## Anatomy of a Source plugin

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

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

e.g. it exports a `sourceFiles()` method which returns a `Promise` resolving
an `Array` of [Virtual Files](usage/pipeline-plugins.md#virtual-files).

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

```js title="simple-sql-source-plugin.js"
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`:

```js title="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"
      }
    }
  ]
  // ...
}
```