SYNOPSIS
exp
--abort
--chdir directory
--clean
--listen IP:PORT
--log path:level
--noclean
--norender
--nowatch
--quiet
--trace path:level
--verbose dir
--version
commands ...
Commands:
clean
deploy [directory]
edit key[=value]
init
mode [debug|release|...]
render
serve
watch
FILES ...
<;CR>;
DESCRIPTION
Expansive is a fast and flexible static web site generator. It quickly
creates HTML pages from layouts, partials and content pages. Expansive
brings dynamic content to static web sites.
Expansive includes flexible tooling so you can build your site in
development mode and painlessly switch to production mode for release. It
will minify, compress and bundle your site for easy deployment.
WHY EXPANSIVE?
There are many web site site generators, why another one? Most existing
site generators are slow, often painfully slow. When creating or
managing a web site, you need tools that do not delay the creative design
process. They need to be as fast as possible. Expansive is designed to
be fast, without sacrificing features.
FEATURES
Expansive generates static web sites from pages, layouts, partials and
scripts. It has the following major features:
NICE PARTS
While Expansive has a strong feature set, there are some characteristics
that make Expansive particularly sweet.
. Fast, fast, fast
. Embedded Ejscript for server-side Javascript in every page
. Easy to create and install new plugins
. Great diagnostics when things go wrong
BASIC USAGE
To prepare a directory for expansive and create an expansive.json
configuration file:
expansive init
To install new plugins to transform content, use the Pak command. The
exp-less compiles *.less into css.
pak install exp-less
To render a site from 'contents' into 'dist'. This processes web pages
under the 'contents' directory into the 'dist' directory for production.
expansive render
To serve content and watch for changes
expansive serve
or
expansive
To watch for changes but not serve
expansive watch
To render a matching set of files
expansive contents/index.html
expansive contents/manual
To deploy a rendered site
expansive deploy directory
To clean the rendered site under 'dist'
expansive clean
DIRECTORIES
directories. It uses layout pages from the 'layouts' directory and
includes partial pages from the 'partials' directory. Raw files may be
copied from the 'files' directory. Documents are rendered to the 'dist'
output directory.
CONFIGURATION
Expansive is controlled by an 'expansive.json' configuration file. This
defines top level configuration for the site and controls how Expansive
renders the site. An expansive.json file must be present for Expansive to
render content.
To prepare a new site to use Expansive, run:
expansive init
This creates an expansive.json and package.json file. The expansive.json
file controls Expansive execution. The package.json file is used by the
Pak manager when installing or managing extension packages.
{
meta: {
site: 'http://example.com',
sitemap: {
files: [
'**.html',
!**unsupported.html'
]
}
},
control: {
copy: [ 'images' ],
listen: '127.0.0.1:4800'
}
}
Expansive uses a liberal json format that permits comments, unquoted
property keys and use of multi-line quotes. The layout and partial page.
The 'control' collection has properties that control the operation of
Expansive. These values are made available to web pages via the
'expansive.control' property.
In the 'control' section, the 'documents' array defines the set of
patterns to select documents from the 'contents' directory for
processing. The 'copy' array defines a set of patterns to select files
to copy without processing. The copy patterns are relative to the
'contents' directory.
DYNAMIC CONTENT
the Javascript expression, HTML escapse the data and then write it. For
example:
<;p>;Today is <;@= Date() @>;
Even simpler, you can use an abbreviated @= variable to emit the value of
a Javascript variable. For example:
<;p>;Site URL is @={meta.site}<;/p>;
The top URL of the site may be abbreviated as '@~'.
TRANSFORMATIONS
Expansive will interpret document extensions and automatically transform
content from one format to another. For example, the filename
'instructions.html.md' tells Expansive that the data is in Markdown
format via the '.md' extension and it should be converted to 'html'.
Expansive will examine each nested extension and process the document
until it reaches an extension for which there is no further
transformations defined.
Expansive uses the '.exp' extension to specify the document has embedded
Javascript. For example:
index.html.md.exp
This means the file has Embedded Javascript in a Markdown file that will
be compiled to HTML. Expansive will process this by first running the
embedded Javascript, then piping the result through the Markdown filter
and finally saving the result as 'index.html'.
The transformation pipeline for specific extensions can be overridden via
the 'expansive.transforms' meta property.
PLUGINS
Expansive may be extended via plugins that provide transformations and
additional scripting capability. Plugins are installed using the Pak
manager via 'pak install NAMES...'. Once installed, expansive will load
all installed plugin packages.
USEFUL PLUGINS
Here are some of the more useful Expansive plugins:
exp-bash Run shell scripts and capture the output.
exp-css Process CSS files to add browser specific prefixes and minify
the output. Requires 'autoprefixer' and 'recess' to be
installed.
Many plugins can be customized by passing configuration to the plugin via
expansive.json file. For example: To request that all Javascript files be
minified, use a '.min.js' extension, and be compressed but not managed:
{
services: {
'minify-js': {
compress: true,
mangle: true,
dotmin: true
}
}
}
See specific plugin documentation for the configuration options for each
plugin.
LAYOUTS
A layout page defines the top level HTML content for a set of pages. The
layout defines the format, look and feel of the web site so that each
pages does not need to replicate this content. Document pages nominate a
layout page to use, and the layout page then wraps the content page to
create a composite page. The '<;@ content @>;' tag in the layout is
replaced with the web page content after separating the page meta data.
There can be multiple layout pages and the default layout is called
'default.html.exp'. This may be modified by setting the 'layout' meta
property to an alternate layout name. Set to '' to disable layout
processing. Layout pages may nest, i.e. may use other layout pages.
Layout pages can use any desired transformation file extension.
<;!DOCTYPE html>;
<;html lang="en">;
<;head>;
<;title>;<;@= meta.title @>;<;/title>;
<;link href="css/api.css" rel="stylesheet" type="text/css" />;
<;/head>;
<;body>;
<;div class="content">;
<;@ content @>;
<;/div>;
<;/body>;
<;/html>;
PARTIALS
Web pages often need to have content that is common across a set of
pages. Expansive supports this via partial pages that can be included by
any page, layout or other partial page. A page specifies a partial by
using the 'partial' Javascript function. For example:
META DATA
Pages, layouts and partials can define meta data at the top of the file
via a Javascript literal. Meta data is passed to the Javascript
execution context for each page, layout and partial where scripts can
examine and use in rendering pages.
{
draft: true,
navigation: 'blog',
}
<;h1>;Page Header<;/h1>;
The meta data is added to the current meta data collection from the
expansive.json file and passed to the layout page, partials pages and
content pages. The meta data can be accessed via the global 'meta'
Javascript variable.
Meta data is inherited and aggregated as Expansive processes a web site
directory. In each directory, a site may define an 'expansive.json' file
that provides additional meta data for that directory level. The meta
data from upper directories is passed down to lower directories. In this
manner upper levels can define the parameters for subdirectories in the
site. Meta data is never passed back up the tree.
META PROPERTIES
Expansive defines a rich set of meta properties for you to use in your
pages:
date Generation date of the document.
description Description of the web site. Sourced from the 'description'
property in the package.json file.
dest Final destination name of the rendered document or file in
the 'dist' directory.
document Input file name of the document being processed. For partials
and layouts, this is set to the invoking document.
extension The extension of the public document filename.
extensions The set of extensions on the original input document.
from The filename extension being processed by the current
transformation.
isLayout True if a layout is being processed.
isPartial True if a partial page is being processed.
site URL for the home page of the web site.
sitemap Control what files to include in a sitemap. If defined,
Expansive will by default include all HTML files in the
sitemap. To change the file set included in the sitemap,
define a 'files' property with an array of patterns in the
sitemap object.
sitemap: {
files: [ '**.html', '!draft.html' ],
}
source Current input source file being processed. May be a document,
partial, layout or any input resource file. Includes the
contents, lib, layouts or partials directory.
sourcePath Source filename relative to the contents, lib, layouts, or
partials directories.
title Title of the web site. Sourced from the 'title' property in
the package.json file.
to The destination filename extension after processing by the
current transformation.
top URL for the top level home page of the site.
url URL for the current page.
EXPANSIVE CONTROL
Expansive defines a set of control properites in the meta.expansive
property. These are originally sourced from the 'control' property in the
'expansive.json' file.
copy Array of patterns to copy without processing. The patterns
may include "*" or "**". If a directory is specifed, all
files under the directory are copied. The files are relative
to the 'contents' directory.
documents Array of patterns to process. The patterns may include "*" or
"**". If a directory is specifed, all files under the
directory are processed. The files are relative to the
'contents' directory.
files Array of directories containing raw content to copy to 'dist'
without processing. By default, contains 'files'.
listen Address on which to listen for HTTP requests. May be just a
port number.
}
Some of the standard service names are: compile-esp, compile-
less, compile-markdown, compile-sass, compress, minify-css,
minify-js, prefix-css, shell.
watch Time in milliseconds to wait between checking for rendering.
CREATING PLUGINS
Expansive plugins are created using the Pak utility
(https://www.embedthis.com/pak) and published to the Pak Catalog at
(https://www.embedthis.com/catalog/). The plugin contains an expansive.json
file that includes transforms relevant to the plugin. For example:
{
expansive: {
transforms: {
name: 'my-transform',
mappings: {
ext1: 'ext2',
},
script: '
function transform(contents, meta, service) {
return transformed data
}
'
}
}
}
The plugin specifies a one or more transformations via the 'transforms'
collection. Each transform definition provides an implemention of a
transform service. The 'name' property specifies the transform service
name. The service name provides an abstract name for which multiple
plugins may provide the implementation.
The 'mappings' property specifies a set of the input and output filename
extensions used when transforming documents. If all extensions are
supported, set the value to '*'. The value may be an arrays if multiple
extensions are supported. Extensions may be multipart, for example:
'min.js'.
The transform script should define a global 'transform' function that
will be invoked for matching content. It is invoked with the 'contents'
to transform (String), the meta data collection and the service object
that contains service options. The function should return the
transformed data.
A plugin may also define other Javascript functions and variables in
'script' that will be injected into the global scope of Expansive when it
Configuration for a service can be specified in a property collection
named for the service. If the service name is set to false, the service
is disabled. See the plugin specific README documentation for supported
configuration properties for each service.
SCRIPTING
Expansive defines a Javascript global "expansive" to access and manage
Expansive services. This object provides the following methods:
addItems(collection, items)
Add items to a named collection. Collections are globally defined
and reset at the start of processing for each document.
Documents, partials and layouts can inject items into collections
for sharing to other documents. Items may be a string or an array
of strings. Items are uniquely added to the collection.
getFiles({key: value})
To return a list of matching documents that have meta data
matching the specified keys and values.
getFileMeta(filename)
To return the meta data specified in the given file.
getItems(collection)
Return the items in a named collection as an Array.
removeItems(collection, items)
Remove the specified items from the named collection.
renderScripts
Render all scripts added to the 'scripts' collection via
'addItems'. This permits documents, partials and layouts to
require Javascripts and have them emitted uniquely by a partial.
Requires the exp-js plugin.
renderStyles
Render all stylesheets added to the 'styles' and 'inline-styles'
collections via 'addItems'. This permits documents, partials and
layouts to require stylesheets and have them emitted uniquely by a
partial. Requires the exp-css plugin.
trace(tag, msg...)
To emit console trace while processing.
COMMANDS
clean Remove rendered content from the 'dist' output directory.
deploy Deploy rendered content to a directory. This by default copies
'dist', 'cache', and expansive.json to 'deploy'.
remains in the local Pak cache.
upgrade
Upgrade a plugin version in the local Pak cache.
watch Watch for changes to 'contents', 'layouts' and 'partials' and
render the modified files. Changes to 'layouts' or
serve Serve the web site. By default Expansive will listen on port
4000. This can be modified via the 'listen' property in the meta
collection. Running expansive without any arguments is the same
as "expansive serve".
patterns ...
Providing a list of patterns to filter the set of documents to
render. Expansive will render only the documents that begin with
the given patterns.
OPTIONS
--abort Abort processing on render errors.
--chdir directory
Change to directory before running.
--clean Clean output "dist" directory first.
--listen IP:PORT URI
Change the port on which Expansive will listen. Can omit the IP
portion and only specify a port.
--log filename:level
Emit trace to the specified file. The level is a verbosity
level from 0-5 with 5 being the most verbose.
--noclean Do not clean the 'dist' directory before rendering. By default
Expansive will remove all the content under 'dist' first.
--norender
Do not do an initial render before watching for changes.
--nowatch Do not watch for changes when serving content.
--DIGIT Emit log and HTTP trace to stderr at the specified level. The
DIGIT must be 0 to 5 with 5 being the most verbose. This
option is the same as "--log stderr:DIGIT --trace stderr:DIGIT"
REPORTING BUGS
Report bugs to dev@embedthis.com.
COPYRIGHT
Copyright © Embedthis Software. MakeMe, Pak and Ejscript are a trademarks
of Embedthis Software.
SEE ALSO
ejs, esp, me, pak, http://embedthis.com/expansive/
exp March 2014 EXP(1)
Man(1) output converted with
man2html