Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    pacmanpublic

    This package has been deprecated

    Author message:

    Pacman has been renamed to Pacbot

    Pacman

    Pacman is a fast static site generator, built primarily for large single-page webapps. While there are many static site generators, few are built to work with lots of files. The main problem is in development mode, where many static site generators regenerate all files when a single file changes. If you have a lot of files, this means waiting a few seconds before you can see your changes in the browser. Features:

    • Regenerating files on the fly
    • HTML microtemplates
    • Layouts and partials
    • Asset packaging
    • Deploy via rsync
    • Staying out of your way

    Pacman has two distinct modes: dev mode and build mode.

    • In dev mode, all files are served on the fly, without regenerating the entire site.
    • In build mode, all files are processed and all assets are packed into an uploadable dir.

    Install

    To install pacman, use npm:

    $ npm install pacman -g
    

    Setup

    Pacman could be used in a directory with the following structure:

    mysite/
        config.js        -- the pacman config file (more on this later)
        public/          -- the folder where the build-mode generated site is placed
        content/         -- the content for your site
            index.html   -- an index file for your site, along with any other file
            _partials/   -- a folder with all your partials
            _layouts/    -- a folder with all your layouts
    
    • Pacman will generate content from the content directory,
    • The resulting site will be placed in the public directory.
    • You can change the names of these folders from the command line, or in the config.js file.
    • Files or folders starting with _ will not be processed into the public directory.
    • Other than that, the names of the folders are not important in any way.

    Usage

    Here is how to use Pacman from the command line:

    Usage: pacman [options]
    
    Options:
    
      -h, --help       output usage information
      -V, --version    output the version number
    
      -d, --dev        serve content directly from source folder
      -b, --build      build a complete version, with packed assets
      -s, --sync       sync target dir to remote server or local dir
    
      --port   <port>  change dev server port    (default 3000)
      --config <path>  change config file        (default ./config.js)
      --source <path>  change source directory   (default ./content)
      --target <path>  change target directory   (default ./public)
      --remote <path>  set remote server address (no default)
    

    Here are some common use cases:

    # Development mode: serve files directly from ./content
    $ pacman -d
    
    # Build mode: process all files and assets into ./public
    $ pacman -b
    
    # Sync: rsync target directory to your remote server
    $ pacman -s --remote user@example.com:/path/to/document/root/
    
    # Build and sync to different local folder
    $ pacman -b -s --remote relative/target/folder
    

    API

    You may also use pacman programmatically:

    var pacman = require("pacman");
     
    // Set config flags
    pacman.config({
      source: "relative/source/folder/name",
      target: "relative/target/folder/name",
      remote: "foo@example.com:/path/to/document/root/"
    });
     
    // Start dev mode
    pacman.dev();
     
    // Start build mode
    pacman.build();
     
    // Sync target dir
    pacman.sync();

    Templates

    Pacman uses JS microtemplates from Underscore.js to parse HTML files. For example, putting the following in your HTML file will output the current Unix timestamp:

    <%= (new Date()).getTime() %>
    

    You also have a few built-in helpers, most importantly get(key) and set(key, value) which can be used to pass variables between files, partials and layouts. These variables are reset between each individually generated page.

    Partials

    Partials are small bits of HTML that you need on more than one page. Render another HTML file (most often from your _partials directory) by using the partial helper:

    <%= partial("_partials/myFile.html") %>
    

    Putting your partials in a folder starting with _ ensures that they will not be copied into the public folder by themselves, but only as part of other files.

    Layouts

    Layouts are used to surround your HTML files with standard content, like the doctype, your menu and footer. Place your layout in _layouts/default.html, and it will be used automatically. In your layout, you have the variable content, which denotes where the main content should be placed:

    <!doctype html>
    <html>
    <head>
        <title>My Site</title>
    </head>
    <body>
        <%= content %>
    </body>
    </html>
    

    You can use different layouts for different files. This is specified in your config.js file (explained at the end of this readme):

    exports.config = {
      layouts: {
        "mypage.html": "_layouts/other.html"
      }
    };

    Create an object with your custom layouts, called layouts, where each key should be a substring of the file path to match, and the value points to the layout file.

    Assets

    Assets (for now, just JS and CSS files) are served as they are in dev mode, and concatenated and minified in build mode. Which assets belong in which group is specified in the config.js file (see the next section). To include your assets, use the assets helper, quite possibly in your layout file:

    <!doctype html>
    <html>
    <head>
        <title>My Site</title>
        <%= assets("css", "group1") %>
    </head>
    <body>
        <%= content %>
        <%= assets("js", "group2") %>
    </body>
    </html>
    

    Config

    Pacman will look for a config.js file in the directory in which it is run. You can override where to look for the config with the -c command line flag. The config is a valid node.js module. Here is an example:

    exports.config = {
     
      assets: {
        css: {
          group1: [
            "css/1.css",
            "css/2.css"
          ]
        },
        js: {
          group2: [
            "js/a.js",
            "js/b.js"
          ]
        },
      },
     
      helpers: {
        hello: function() {
          return "hello!";
        }
      }
     
    };

    The main purpose of the file is to specify assets (in order), any default command line flags, and any custom HTML helper functions.

    In this example, we have two types of assets (CSS and JS), which each have one group of assets. If the order is not important, you can use folder names instead of filenames, and each file in that directory will be included. Each asset file path is suffixed with a ?v=<current_build_timestamp> for proper cache busting. You can disable this with the config.timestamp flag.

    We have a helper function (hello), usable in any HTML file. The assets can be referenced in an HTML file like this:

    <%= assets("css", "group1") %>
    <%= assets("js", "group2") %>
    
    <%= hello() %>
    

    There are many other config flags you may override. For now, see the file lib/config.js for all these flags.


    License: MIT (see LICENSE).

    Keywords

    none

    install

    npm i pacman

    Downloadsweekly downloads

    112

    version

    0.15.0

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar