Reshape Standard Preset

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:

reshape-expressions, default settings
reshape-layouts, default settings
reshape-include, default settings
reshape-content with md and mdi functions that render markdown using markdown-it
reshape-retext with the smartypants plugin
reshape-beautify, default settings
reshape-minify, toggled with the minify option which is false by default. When enabled, it will disable beautify

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()))