--chdir directory
           --listen IP:PORT
           --log path:level
           --trace path:level
           --verbose dir
           commands ...

           deploy [directory]
           edit key[=value]
           mode [debug|release|...]
           FILES ...


       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.


       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.


       Expansive generates static web sites from pages, layouts, partials and
       scripts. It has the following major features:


       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


       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


       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. 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.


       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: '',
                     sitemap: {
                        files: [
                 control: {
                     copy: [ 'images' ],
                     listen: ''

       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.


       the Javascript expression, HTML escapse the data and then write it. For

        <;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 @={}<;/p>;

       The top URL of the site may be abbreviated as '@~'.


       Expansive will interpret document extensions and automatically transform
       content from one format to another.  For example, the filename
       '' 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:


       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.


       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.


       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

       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


       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">;
                 <;title>;<;@= meta.title @>;<;/title>;
                 <;link href="css/api.css" rel="stylesheet" type="text/css" />;
                 <;div class="content">;
                     <;@ content @>;


       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:


       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.


       Expansive defines a rich set of meta properties for you to use in your

       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

       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 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.


       Expansive plugins are created using the Pak utility
       ( and published to the Pak Catalog at
       ( 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:

       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.


       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.

              To return the meta data specified in the given file.

              Return the items in a named collection as an Array.

       removeItems(collection, items)
              Remove the specified items from the named collection.

              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.

              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.


       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 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.


       --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.

                 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"


       Report bugs to


       Copyright © Embedthis Software. MakeMe, Pak and Ejscript are a trademarks
       of Embedthis Software.


       ejs, esp, me, pak,

exp                                March 2014                             EXP(1)

Man(1) output converted with man2html