metalsmith-react-templates

A templating plugin using JSX templates (React / Preact / React-Router etc.)

About

metalsmith-react-templates is a metalsmith plugin to render files using React based templates.

There is also support for other JSX oriented libraries like Preact

Installation

Using npm:

$ npm install --save metalsmith-react-templates

Install other dependencies:

$ npm install react react-dom

If you're using an older version of React, you may need to install an older version of this package.

| React Version | Package Version -------|:-------|:------- 15.x.x | > 5.x.x 0.14.x | 3.x.x or 4.x.x 0.13.x | 2.x.x 0.12.x | 1.x.x

If you're upgrading, you may want to check out the Upgrade Notes

CLI Usage

Install the node modules and then add the metalsmith-react-templates key to your metalsmith.json plugins.

{
  "plugins": {
    "metalsmith-react-templates": true
  }
}

If you want to specify additional options, pass an object:

{
  "plugins": {
    "metalsmith-react-templates": {
      "baseFile": "base.html",
      "isStatic": true,
      "directory": "templates"
    }
  }
}

JavaScript Usage

Simplest use case:

import templates from 'metalsmith-react-templates';

metalsmith.use(templates());

To specify additional options:

metalsmith.use(templates({
    baseFile: 'base.html'
    isStatic: true,
    directory: 'templates'
}));

Usage Notes

Specifying Templates

If an rtemplate field is set in the yaml front matter of your markdown files, metalsmith-react-templates will use the specified template instead of Default.jsx.

You can also set templateKey to other values like template and the plugin will use that value (in this case the template field) instead of rtemplate field in the yaml front matter.

Webpack / Build Systems

If you import css or any other non-standard JavaScript code using require, you might want to make use of the requireIgnoreExt to ignore those files.

You may also add other extensions that are treated as JSX. using requireTemplateExt.

Options

All parameters are optional.

Parameter	Default Value	Description
`baseFile`	`null`	Specifies a file which the contents of the react template will render into. This is similar to the `index.html` file which you `React.render()` your components in. In your base file, put `{{contents}}` in the location where you want your data will render into. You may also override this value by placing a baseFile key in your source file's front matter.
`baseFileDirectory`	`null`	Sets the directory which your baseFile resides. By default, it assumes your base file is in the same directory as your templates.
`defaultTemplate`	`Default.jsx`	The default template file to use if no template is specified. Set to `''` or `null` if you do not want metalsmith to not apply template transformation on files that do not have a 'template / rtemplate' key present.
`directory`	`templates`	Sets the directory which your react templates resides.
`extension`	`.html`	Option to rename your files to a specified extension. Set to `null` if you do not want to change the file extension
`isStatic`	`true`	Since this is a static site generator, by default, it will render the React Templates using `renderToStaticMarkup()`. However, you may choose to make a static site generator with React functionalities (similar to first render from server) and subsequently pull page routes via JavaScript / React. Setting this parameter to `false` will cause templates to be parsed using `renderToString()`.
`pattern`	`*/`	Specifies a file filter pattern.
`preserve`	`false`	Stores a copy of un-templated contents into `rawContents` meta which you can access in your React components.
`props`	`null`	Accepts a `function` returning props or a `string` containing the props to provide to the template. If `null` the defualt set of props will be returned.
`requireIgnoreExt`	`[ ]`	A list of extensions to ignore. For example, `{requireIgnoreExt: ['.css']}` would ignore declarations like `require('file.css')`
`requireTemplateExt`	`['.jsx']`	A list of extensions to treat as JSX.
`templateKey`	`null`	Allows you to specify the key in the markdown file that will serve as the template file name. By default, it is `rtemplate`.
`templateTag`	`null`	Accepts a function `pattern(key)` which returns a regex object used to find and replace template tags in your output file. By default, template tags are assumed to be `{{tag}}`. You may use this to allow for other tag formats (eg. you may want `<!--tag-->` instead). Check the test case for an example.
`tooling`	`{ }`	Options to pass into the `babel` transpiler.

Deprecated Options

Parameter	Default Value	Description
`propsKey`	`null`	Specifies a key containing the props to provide to the template. If left unspecified, a generic props containing all keys is provided.
`noConflict`	`true`	By default, this plugin will read from the `rtemplate` key in your `yaml` front matter. However, if this is the only templating plugin, you may set `noConflict` to `false` to use the `template` key instead.

jsx-render-engine

jonathanglasmeyer/metalsmith-react-templates