a standard plugin pack with modern template language features
JavaScript
Latest commit 3a23727 Feb 3, 2018

README.md

Reshape Standard Preset

npm tests dependencies coverage

A standard, opinionated preset for reshape

Note: This project is in early development, and versioning is a little different. Read this for more details.

Installation

npm install reshape-standard -S

Note: This project is compatible with node v6+ only

Example

The standard preset includes plugins that cover all the features needed from a modern template engine. Below is an example of a page utilizing many of the features:

<!doctype html>
<html>
  <head>
    <title>Standard Example</title>
  </head>
  <body>
    <h1>Hello world!</h1>

    <ul id='nav'>
      <li class='active'><a href='#'>home</a></li>
      <li><a href='#'>about</a></li>
    </ul>

    <include src='_welcome_message.sgr'></include>

    <p>local variable: {{ foo }}</p>

    <each loop='item of items'>
      <if condition='item.name'>
        <p>{{ item.name }}</p>
      </if>
      <else>
        <p>item with no name!</p>
      </else>
    </each>

    <p mdi>**Look** at this [markdown](https://daringfireball.net/projects/markdown/)</p>
  </body>
</html>

Note that it is easily possible to configure any of the options. If you don't like the names of any of the custom tags, you can change them in the options. If you don't like the {{ }} delimiters, you can quickly and easily change them, etc. See the options below for more!

Many also enjoy using a more jade/pug/haml-like whitespace syntax. It's quite easy to add in sugarml for this if you want by adding it as a dependency, requiring it, and passing { parser: sugarml } into the options.

Usage

This is nothing more than a light wrapper around a reshape configuration object. Options are filtered into their appropriate plugins internally. All are optional.

const reshape = require('reshape')
const standard = require('reshape-standard')

reshape(standard(/* options */))
  .process(someHtml)
  .then(res => console.log(res.output()))

By default, the standard preset includes:

Based on the way they are ordered there are a couple limitations to keep in mind:

  • You cannot use a layout block/extend inside of an include
  • Any expression delimiters rendered from a content or retext transform will be output as plaintext, not as an expression
  • Output from a content transform will be processed by retext in that order

Any of these plugins can be customized by passing options described below.

Options

Name Description Default
root Root path used to resolve layouts and includes
filename Name of the file being compiled, used for error traces and as the include/layout root if not otherwise provided
delimiters Delimiters used for html-escaped expressions ['{{', '}}']
unescapeDelimiters Delimiters used for unescaped expressions ['{{{', '}}}']
markdown Options passed in to markdown-it constructor { typographer: true, linkify: true }
markdownPlugins Plugins to be loaded by markdown-it parser. See below for more details.
content Options passed to the reshape-content plugin { md: renderMarkdown, mdi: renderMarkdownInline }
parser custom html parser if desired
retext Plugins to be passed to the reshape-retext plugin [smartypants] (ref)
locals Added directly to the output object, used when compiling a reshape template to html {}
alias Alias option to be passed to the include plugin
parserRules Parser rules to be passed to the include plugin
minify Minifies the html output by removing excess spaces and line breaks, comments, and by minifying inline CSS, JS, SVG and JSON. Accepts a boolean or an object of options passed to reshape-minify false
appendPlugins Adds a single plugin or array of plugins after all the defaults
prependPlugins Adds a single plugin or array of plugins before all the defaults
template Set this to true if you are trying to output a client-side template function. false
locals Optionally set your locals as soon as expressions are evaluated.
multi Pass through feature specific to reshape-loader

Markdown Rendering Functions

There are two markdown rendering shortcut functions provided with this preset: md and mdi. The md function will run a full markdown render including wrapping with a paragraph tag, rendering headlines, etc. For example:

<div class='content' md>
  # The title

  Here's some text, wow.

  A second paragraph!
</div>

This would work as expected, rendering title and paragraph tags:

<div class='content'>
  <h1>The title</h1>
  <p>Here's some text, wow.</p>
  <p>A second paragraph!</p>
</div>

The mdi shortcut is specifically for rendering inline markdown, not including any type of title tags or paragraph wrapping. So for example:

<p mdi>Hello, I am #1 and this is [my link](#).</p>

Would render without additional paragraph wrappings or unexpected title renders:

<p>Hello, I am #1 and this is <a href='#'>my link</a>.

Markdown Plugins

You can pass an array of markdown-it plugins via the markdownPlugins option with or without their own options.

const reshape = require('reshape')
const standard = require('reshape-standard')
const emoji = require('markdown-it-emoji')
const anchor = require('markdown-it-anchor')
const toc = require('markdown-it-table-of-contents')

reshape(
  standard((markdownPlugins: [emoji, anchor, [toc, { containerClass: 'toc' }]]))
)
  .process(someHtml)
  .then(res => console.log(res.output()))

License & Contributing