This plugin for [Metalsmith][] is aimed at generating documents written for **[groff][]**. It has very few Javascript dependencies, but expects **groff** to be correctly installed on the system.
If using the CLI for Metalsmith, metalsmith-groff can be used like any other plugin by including it in `metalsmith.json`.
```json
{
"plugins": {
"metalsmith-groff": {}
}
}
```
In Metalscript's JavaScript API, metalsmith-groff can be used like any other plugin by attaching it to the function invocation chain on the Metalscript object.
```js
const groff = require('metalsmith-groff')
require('metalsmith')(__dirname)
.use(groff())
.build()
```
If metalsmith-groff is used as above without any argument, it will handle any file ending with `.ms`, `.me`, `.mm` or `.mom` and call **groff** with the eponymous macro to build a PDF document. The original file is dropped and replaced by the produced PDF one. To extend this default behaviour, it is possible to provide options as a simple objet.
## Options
Here are the options handled by the plugin. A good share of them is used to configure the call to **groff**, so reading **groff** manual will provide additional and useful information.
-`device` is the **groff** output device to be used. Default is `pdf`, and other common devices provided with **groff** are `html` or `ps`.
-`encoding` sets the input encoding. It is the `-K` option of **groff** and defaults to `utf8`.
-`macroPaths` is an array of additional paths to search for macros. The default value is empty, see `man groff_tmac` for further explanation about the search sequence.
-`pattern` is the matcher used to determine the files to be transformed. It is used with **[minimatch][]**. The default value (`**/*.@(me|mm|ms|mom)`) matches all files ending with `.ms`, `.me`, `.mm` or `.mom` at any depth.
