Fix TS & JSDoc descriptions, add defaults & example

lib/index.d.ts

@@ -1,5 +1,4 @@
 import { Plugin } from "metalsmith";
-import getTransformer from "./get-transformer";
 
 export default layouts;
 export type Render = (source: string, options: any, locals: any) => string;
@@ -24,19 +23,22 @@ export type Options = {
     /**
      * Jstransformer to run: name of a node module or local JS module path (starting with `.`) whose default export is a jstransformer. As a shorthand for existing transformers you can remove the `jstransformer-` prefix: `handlebars` will be understood as `jstransformer-handlebars`. Or an actual jstransformer; an object with `name`, `inputFormats`,`outputFormat`, and at least one of the render methods `render`, `renderAsync`, `compile` or `compileAsync` described in the [jstransformer API docs](https://github.com/jstransformers/jstransformer#api)
      */
-    transform?: string|JsTransformer
+    transform: string|JsTransformer
     /**
      * A default layout to apply to files, eg `default.njk`.
+     * @default null
      */
     default?: string;
     /**
-     * The directory for the layouts. The default is `layouts`.
+     * Only files that match this pattern will be processed. Accepts a string or an array of strings.
+     * @default '**'
      */
-    pattern?: string;
+    pattern?: string|string[];
     /**
-     * Only files that match this pattern will be processed. Accepts a string or an array of strings. The default is `**` (all).
+     * The directory for layouts, relative to `metalsmith.directory()`.
+     * @default 'layouts'
      */
-    directory?: string | string[];
+    directory?: string;
     /**
      * Pass options to [the jstransformer](https://github.com/jstransformers/jstransformer) that's rendering your layouts. The default is `{}`.
      */
@@ -46,12 +48,24 @@ export type Options = {
      */
     extname?: string;
 };
+
 /**
  * A metalsmith plugin for rendering layouts
- * @param {Options} options
- * @returns {import('metalsmith').Plugin}
+ * @example
+ * import nunjucks from 'jstransformer-nunjucks'
+ *
+ * metalsmith
+ *  .use(layouts({ transform: 'jstransformer-nunjucks' })) // use jstransformer-nunjucks
+ *  .use(layouts({ transform: 'nunjucks' }))               // shorthand for above
+ *  .use(layouts({ transform: nunjucks }))                 // equivalent to above
+ *  .use(layouts({ transform: './local/transform.js' }))   // custom local transformer
+ *  .use(layouts({ transform: {                            // custom inline transformer
+ *     name: 'prepend-hello',
+ *     inputFormats: ['prepend-hello'],
+ *     outputFormat: 'html',
+ *     render(str, options, locals) => {
+ *       return 'hello ' + str
+ *     }
+ *   }}))
  */
-declare function layouts(options: Options): Plugin;
-declare namespace layouts {
-    export { getTransformer };
-}
+declare function layouts(options: Options): Plugin;

src/index.js

@@ -53,9 +53,9 @@ let debug = () => {
 /**
  * @typedef {Object} Options `@metalsmith/layouts` options
  * @property {string|JsTransformer} transform Jstransformer to run: name of a node module or local JS module path (starting with `.`) whose default export is a jstransformer. As a shorthand for existing transformers you can remove the `jstransformer-` prefix: `marked` will be understood as `jstransformer-marked`. Or an actual jstransformer; an object with `name`, `inputFormats`,`outputFormat`, and at least one of the render methods `render`, `renderAsync`, `compile` or `compileAsync` described in the [jstransformer API docs](https://github.com/jstransformers/jstransformer#api)
- * @property {string} [default] A default layout to apply to files, eg `default.njk`.
- * @property {string} [pattern] The directory for the layouts. The default is `layouts`.
- * @property {string|string[]} [directory] Only files that match this pattern will be processed. Accepts a string or an array of strings. The default is `**` (all).
+ * @property {string} [default=null] A default layout to apply to files, eg `default.njk`.
+ * @property {string|string[]} [pattern='**'] Only files that match this pattern will be processed. Accepts a string or an array of strings. The default is `**` (all).
+ * @property {string} [directory='layouts'] The directory for the layouts. The default is `layouts`.
  * @property {Object} [engineOptions] Pass options to [the jstransformer](https://github.com/jstransformers/jstransformer) that's rendering your layouts. The default is `{}`.
  * @property {string} [extname] Pass `''` to remove the extension or `'.<extname>'` to keep or rename it. By default the extension is kept
  */