metalsmith-pug-extra

Metalsmith plugin to convert or compile and render Pug files.

In addition to metalsmith-pug:

• API to execute render after compile

  You can insert metalsmith-collections, metalsmith-permalinks, etc. between compile and render. This is the biggest reason for this package to exist.

• Modify metadata after conversion and reconvert

  You can convert the converted HTML as many times as you like. For example, you can use metalsmith-excerpts for converted HTML and convert the HTML again using the retrieved excerpt values.

• Customizable rename logic

  You can freely specify the file name after conversion. See the renamer option.

• Option to prohibit overwriting

  You can specify not to overwrite files if they are duplicated. See the overwrite option.

• Available in TypeScript

  Type definition is included.

Install

npm install --save metalsmith-pug-extra

Usage

convert()

Convert template files to HTML.

const Metalsmith = require('metalsmith');
const { convert } = require('metalsmith-pug-extra');

const options = {
  pattern: ['**/*.pug', '**/*.jade'],
  overwrite: false,
  copyFileData: true,
  useMetadata: true,
  locals: {
    postName: 'good post name'
  }
};

Metalsmith(__dirname)
  .use(convert(options))

compile() & render()

After compiling the template file, it is processed by plugins such as renaming (metalsmith-collections and metalsmith-permalinks in this example) and finally the HTML content is generated.

const Metalsmith = require('metalsmith');
const collections = require('metalsmith-collections');
const permalinks  = require('metalsmith-permalinks');
const { compile, render } = require('metalsmith-pug-extra');

const compileOptions = {
  pattern: ['**/*.pug', '**/*.jade'],
  overwrite: false,
  copyFileData: true
};
const renderOptions = {
  useMetadata: true,
  locals: {
    postName: 'good post name'
  }
};

Metalsmith(__dirname)
  .use(compile(compileOptions))
  .use(collections({
    posts: 'posts/*.html'
  }))
  .use(permalinks())
  .use(render(renderOptions))

API

convert(options?)

Returns a plugin that converts Pug template files to HTML files.
Except for differences in options, this is equivalent to such as metalsmith-pug and metalsmith-in-place.

Options

Only files that match this pattern will be processed.
Specify a glob expression string or an array of strings as the pattern.
Pattern are verified using multimatch v4.0.0.

Default value:

['**/*.pug']

Type definition:

string | string[]

Convert template filename to HTML filename.
Specifies a function to convert strings.

Default value:

filename => filename.replace(/\.(?:pug|jade)$/, '.html')

Type definition:

(filename: string) => string

If set to true, the file with the same name as the converted HTML will be overwritten.
If set to false, the file with the same name as the converted HTML is prioritized and HTML is not generated.

Default value:

true

Type definition:

boolean

If set to true, the template file metadata is copied to the converted HTML file.

Default value:

false

Type definition:

boolean

Pass additional local values to the template.
If useMetadata option is true, this value will be overwritten with Metalsmith's metadata.

Default value:

{}

Type definition:

// see https://github.com/DefinitelyTyped/DefinitelyTyped/blob/54642d812e28de52325a689d0b380f7a4d3c113e/types/pug/index.d.ts#L133-L138
{
    [propName: string]: any;
}

If set to true, passes Metalsmith's global metadata and file metadata to the template.

Default value:

false

Type definition:

boolean

Other properties are used as options for Pug v2.0.4.
In internal processing, it is passed as an argument of pug.compile() function.
Please check Pug Options for more details.

convert.defaultOptions

Default value of the convert() function options argument.
It can be used to specify an options based on the default value.

Metalsmith(__dirname)
  .use(convert({
    pattern: [].concat(convert.defaultOptions.pattern, '!**/_*', '!**/_*/**')
    // equals to: [ '**/*.pug', '!**/_*', '!**/_*/**' ]
  }))

compile(options?)

Returns a plugin that compiles Pug templates.

The file name is changed to *.html but the template is not converted.
You can use other plugins to generate locals before converting the template with the render() plugin.

Options

Only files that match this pattern will be processed.
Specify a glob expression string or an array of strings as the pattern.
Pattern are verified using multimatch v4.0.0.

Default value:

['**/*.pug']

Type definition:

string | string[]

Convert template filename to HTML filename.
Specifies a function to convert strings.

Default value:

filename => filename.replace(/\.(?:pug|jade)$/, '.html')

Type definition:

(filename: string) => string

If set to true, the file with the same name as the converted HTML will be overwritten.
If set to false, the file with the same name as the converted HTML is prioritized and HTML is not generated.

Default value:

true

Type definition:

boolean

If set to true, the template file metadata is copied to the converted HTML file.

Default value:

false

Type definition:

boolean

Other properties are used as options for Pug v2.0.4.
In internal processing, it is passed as an argument of pug.compile() function.
Please check Pug Options for more details.

compile.defaultOptions

Default value of the compile() function options argument.
It can be used to specify an options based on the default value.

render(options?)

Returns a plugin that generates HTML content from a compiled template.
Files compiled with the compile() function are processed.

This plugin can also reconvert generated HTML.
Therefore, you can use metalsmith-excerpts etc. effectively.

Options

Pass additional local values to the template.
If useMetadata option is true, this value will be overwritten with Metalsmith's metadata.

Default value:

{}

Type definition:

// see https://github.com/DefinitelyTyped/DefinitelyTyped/blob/54642d812e28de52325a689d0b380f7a4d3c113e/types/pug/index.d.ts#L133-L138
{
    [propName: string]: any;
}

If set to true, passes Metalsmith's global metadata and file metadata to the template.

Default value:

false

Type definition:

boolean

Only files that match this pattern will be processed.
Specify a glob expression string or an array of strings as the pattern.
Pattern are verified using multimatch v4.0.0.

Default value:

['**/*']

Type definition:

string | string[]

If set to true, it will reuse the options value set in the render() function just before.
This option is intended to improve the convenience of regenerating generated HTML.

Default value:

false

Type definition:

boolean

Example:

const Metalsmith = require('metalsmith');
const excerpts = require('metalsmith-excerpts');
const { compile, render } = require('metalsmith-pug-extra');

Metalsmith(__dirname)
  .use(compile({ copyFileData: true }))
  .use(render({
    locals: {
      a: 1,
      b: 2,
    },
    useMetadata: true,
    pattern: ['articles/*'],
  }))
  .use(excerpts())
  .use(render({
    reuse: true,
    pattern: render.defaultOptions.pattern,
    /*
    equals to:
    {
      locals: {
        a: 1,
        b: 2,
      },
      useMetadata: true,
      pattern: render.defaultOptions.pattern,
    }
    */
  }))

render.defaultOptions

Default value of the render() function options argument.
It can be used to specify an options based on the default value.

Debug mode

This plugin supports debugging output.
To enable, use the following command when running your build script:

DEBUG=metalsmith-pug-extra:* node my-website-build.js

For more details, please check the description of debug v4.1.1.

Tests

To run the test suite, first install the dependencies, then run npm test:

npm install
npm test

CLI Usage

For now, this plugin does not support Metalsmith CLI.
I am planning to add Metalsmith CLI support in version 2.x.
See #28 for details.