EXP(1)                           User Commands                          EXP(1)

NAME
       expansive  - Embedthis Expansive -- Fast, Flexible Static Web Site Gen-
       erator

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 man-
       aging 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:

           . Javascript templates for dynamic content
           . Layout pages to define the look and feel of site
           . Partial pages to include replicated content
           . Per-page meta data to control layouts and partials
           . Integrated web server to serve content
           . Watches for changes and automatically render site
           . Scripting support via change events
           . Automatic sitemap creation
           .  Complete  tooling  for  minifying, compression and bundling your
       site
           . Content transition pipeline
           . Open plugin architecture

NICE PARTS
       While Expansive has a strong feature set, there are  some  characteris-
       tics 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 con-
       figuration 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  produc-
       tion.

           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
       Expansive uses the following directories:

           contents    Souce web content to be processed
           dist         Final  output  directory containing the rendered docu-
       ments
           files       Files to be copied and not processed
           layouts     For master page layouts
           partials    For partial web pages that can  be  included  by  other
       pages

       These  directories can be modified via meta 'directories' collection in
       the package.json file.

PROCESSING
       Expansive operates by processing web  pages  from  the  'contents'  and
       'lib'  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 expan-
       sive.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  opera-
       tion 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 pat-
       terns 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
       Expansive uses embedded  Javascript  in  web  pages  to  fully  support
       dynamic content.  Scripts can be embedded via the special Expansive tag
       '<@ ...  @>'. This will run the script when the page  is  rendered  and
       replace  the  script  with  rendered  data.   When the script runs, the
       'this' object is set to the  'expansive'  object  for  easy  access  to
       Expansive methods. See SCRIPTING below for more details.

       For example, to render the current date in a document:

        <p>Today is <@ write(Date()) @>

       The write function is used to render data to be used in place of the <@
       @> element.  You can use 'writeSafe' to HTML  escape  the  data  before
       writing.  You can also use a simpler form <@= that means use the result
       of 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  trans-
       form  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 transforma-
       tions defined.

       Expansive uses the '.exp' extension to specify the document has  embed-
       ded 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.

       exp-esp   Compile ESP web pages and applications.

       exp-gzip  Compress final output using gzip. Files are rendered  with  a
                 'gz' extension.

       exp-js    Process  Javascript  files  to  mangle  and  minify. Requires
                 'uglify' to be installed.

       exp-less  Process Less stylesheets into CSS. Requires  'recess'  to  be
                 installed.

       exp-md    Process Markdown files and emit html.

       exp-sass  Process SASS files into CSS. Requires "sass" 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 nom-
       inate  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  pro-
       cessing.  Layout pages may nest, i.e. may use other layout pages.  Lay-
       out 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:

        <@ partial('header') @>

       The partial function will search for a file starting with 'header.html'
       in the 'partials' directory.  Partials  are  transformed  according  to
       their  extension.  If  a partial called 'header.html.md.exp' was found,
       then it will be first transformed by running the  embedded  Javascript,
       then  piping the output into the Markdown to create html data that will
       then be included in place of the original partial tag.

       Partials can be nested, in that a partial page may include another par-
       ital page to any depth.

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 execu-
       tion  context for each page, layout and partial where scripts can exam-
       ine 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 subdirecto-
       ries 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 par-
                   tials 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.

       layout      Layout page in use. Set to '' if no layout being used.

       mode        Index name in the pak.modes property. The selected property
                   collection is copied up to the top level of the meta  data.
                   This  may be used to select a "debug" or "release" configu-
                   ration.

       partial     Name of the partial page being processed.

       path        Destination filename of the document relative to  the  dist
                   directory.

       service     Name of the transformation service being run.

       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 docu-
                   ment, 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  rela-
                   tive 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.

       script      Script to evaluate  to  inject  code  into  the  Javascript
                   global execution context.

       transforms  Hash  of extension mappings to a list of transform services
                   for those mappings. Mappings are in the form 'ext ->  ext'.
                   For example:

                    transforms: {
                       'less -> css': [
                           'compile-less',
                           'prefix-css',
                           'minify-css',
                           'compress'
                       ]
                    }

                   Some  of  the standard service names are: compile-esp, com-
                   pile-less,   compile-markdown,   compile-sass,    compress,
                   minify-css, minify-js, prefix-css, shell.

       watch       Time  in  milliseconds to wait between checking for render-
                   ing.

CREATING PLUGINS
       Expansive   plugins    are    created    using    the    Pak    utility
       (https://embedthis.com/pak)   and  published  to  the  Pak  Catalog  at
       (https://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 file-
       name extensions used when transforming documents.   If  all  extensions
       are supported, set the value to '*'. The value may be an arrays if mul-
       tiple extensions are supported. Extensions may be multipart, for  exam-
       ple: 'min.js'.

       The  transform  script should define a global 'transform' function that
       will be invoked for matching content.  It is  invoked  with  the  'con-
       tents'  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 executes.

       Web  sites may configure services via properties in the expansive.json.
       For example:

        {
           services: {
               compress: false
               minfiy-css: {
                   minify: true
               }
           }
        }

       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  collec-
              tions  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'.

       init   Initialize  a directory by creating an 'expansive.json' configu-
              ration file.

       install
              Install a plugin from the Pak catalog.

       list   List the installed and uninstalled plugins and packages.

       render Render the site by processing files from 'contents',  'layouts',
              'partials' and 'files' into the 'dist' output directory.

       uninstall
              Uninstall  a  plugin  from  the  expansive.json plugin list. The
              plugin 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.

       --quiet   Run in quiet mode. Do not emit activity trace to the console.

       --trace filename:level
                 Trace  HTTP  requests  to  the specified file. The level is a
                 verbosity level from 0-5 with 5 being the most verbose.  HTTP
                 requests and HTTP headers will be traced at levels 2-4.

       --verbose Run in verbose mode. Emit more activity trace.

       --versions URI
                 Show expansive version information.

       --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 (C) Embedthis Software. MakeMe, Pak and Ejscript are a trade-
       marks of Embedthis Software.

SEE ALSO
       ejs, esp, me, pak, http://embedthis.com/expansive/

exp                               March 2014                            EXP(1)