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.
npm install --save metalsmith-pug-extra
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))
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))
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.
pattern
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[]
renamer
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
overwrite
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
copyFileData
If set to true
, the template file metadata is copied to the converted HTML file.
Default value:
false
Type definition:
boolean
locals
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;
}
useMetadata
If set to true
, passes Metalsmith's global metadata and file metadata to the template.
Default value:
false
Type definition:
boolean
pug options
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.
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', '!**/_*', '!**/_*/**' ]
}))
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.
pattern
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[]
renamer
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
overwrite
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
copyFileData
If set to true
, the template file metadata is copied to the converted HTML file.
Default value:
false
Type definition:
boolean
pug options
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.
Default value of the compile()
function options argument.
It can be used to specify an options based on the default value.
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.
locals
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;
}
useMetadata
If set to true
, passes Metalsmith's global metadata and file metadata to the template.
Default value:
false
Type definition:
boolean
pattern
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[]
reuse
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,
}
*/
}))
Default value of the render()
function options argument.
It can be used to specify an options based on the default value.
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.
To run the test suite, first install the dependencies, then run npm test
:
npm install
npm test
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.