Metalsmith JSTransformers Plugin
Clone or download
Latest commit cced6eb Sep 4, 2018
Permalink
Failed to load latest commit information.
test 1.3.1 May 17, 2018
.editorconfig Update the plugin Jun 26, 2015
.gitignore 0.12.0 Jan 10, 2018
.travis.yml tests: Remove Node 4, 5 and add 10 May 17, 2018
HISTORY.md 1.13.2 May 17, 2018
LICENSE.md 0.13.0 Feb 19, 2018
README.md 0.13.0 Feb 19, 2018
index.js Fix eslint Sep 4, 2018
package.json Fix eslint Sep 4, 2018

README.md

Metalsmith JSTransformer Plugin NPM version

Build Status Dependency Status Greenkeeper badge

Metalsmith plugin to process files with any JSTransformer.

Installation

npm install --save metalsmith-jstransformer

CLI

If you are using the command-line version of Metalsmith, you can install via npm, and then add the metalsmith-jstransformer key to your metalsmith.json file:

{
  "plugins": {
    "metalsmith-jstransformer": {
      "layoutPattern": "layouts/**",
      "defaultLayout": null
    }
  }
}

JavaScript

If you are using the JS Api for Metalsmith, then you can require the module and add it to your .use() directives:

var jstransformer = require('metalsmith-jstransformer');

metalsmith.use(jstransformer({
  'pattern': '**',
  'layoutPattern': 'layouts/**',
  'defaultLayout': null
}));

Convention

Content File Names

Create files that you would like to act on with JSTransformers with file extensions representing the transformer to use, in the format example.html.<transformer>. For example, if you would like to process with Pug, you would name it src/example.html.pug.

Use multiple transformers by appending additional file extension transformer names at the end. For example, to HTML-Minifier our Pug example above, you would use the filename src/example.html.html-minifier.pug.

Example

The following example uses Pug, so we must additionally install jstransformer-pug:

npm install jstransformer-pug --save
src/example.html.pug
---
pageTitle: My Site
pretty: true
---
doctype html
html(lang="en")
  head
    title= pageTitle
  body
    p This is my site!
Result
<!doctype html>
<html>
  <head>
    <title>My Site</title>
  </head>
  <body>
    <p>This is my site!</p>
  </body>
</html>

Layouts

Declare layouts for your content with the extension of the template engine to be used for the layout, in the src/layouts/** directory.

Example

The following example uses Pug and Markdown-it, so we must additionally install jstransformer-pug and jstransformer-markdown-it:

npm install jstransformer-pug --save
npm install jstransformer-markdown-it --save
src/layouts/default.pug
---
pretty: true
---
doctype html
html
  head
    title My Site
  body!= contents

Within the metadata of content in your src directory, tell it which layout to use:

src/index.md
---
layout: layouts/default.pug
---
This is my **site**!

Result

<!doctype html>
<html>
  <head>
    <title>My Site</title>
  </head>
  <body>
    <p>This is my <strong>site</strong>!</p>
  </body>
</html>

Configuration

.pattern

Render content only matching the given minimatch pattern. Defaults to **.

.layoutPattern

The pattern used to find your layouts, from within the Metalsmith source directory. Defaults to layouts/**.

.defaultLayout

If provided, will be used as the default layout for content that doesn't have a layout explicitly defined. Needs to be the full path to the file, from the Metalsmith source directory. Defaults to null.

.engineOptions

Allows passing in options for the given engines.

engineOptions: {
  // Add our own SASS include paths.
  scss: {
    includePaths: [
      'styles/mystyles',
      'node_modules/bootstrap'
    ]
  }
}

.engineLocals

Allows passing in local variables for the given engines.

engineLocals: {
  // All Twig templates will have the `baseURL` local variable.
  twig: {
    baseURL: 'http://mywebsite.com/'
  }
}

License

MIT