---
title: "Plugins"
---

# Plugins

{% alert %}
Please make sure to read [Limedocs Concepts](quickstart) first to understand the mean of plugins.

{% endalert %}

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](https://github.com/vfile/vfile)).

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

```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 your config:

```yaml
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:

```js
// 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