A standard, opinionated preset for reshape
Note: This project is in early development, and versioning is a little different. Read this for more details.
npm install reshape-standard -S
Note: This project is compatible with node v6+ only
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.
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
mdandmdifunctions that render markdown using markdown-it - reshape-retext with the smartypants plugin
- reshape-beautify, default settings
- reshape-minify, toggled with the
minifyoption which is false by default. When enabled, it will disablebeautify
Based on the way they are ordered there are a couple limitations to keep in mind:
- You cannot use a layout
block/extendinside of aninclude - Any expression delimiters rendered from a
contentorretexttransform will be output as plaintext, not as an expression - Output from a
contenttransform will be processed byretextin that order
Any of these plugins can be customized by passing options described below.
| 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 |
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>.
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()))- Details on the license can be found here
- Details on running tests and contributing can be found here