Serum

A simple static website generator


Back to the index

The Command-line Program

Every tasks related to your Serum projects are done by using the Serum command-line program “serum.” This document describes all tasks and options provided by the Serum command-line program.

NOTE

This document assumes that you have installed Serum on an easily reachable directory or you have set $PATH environment variable appropriately.

init — Starts a New Project

% serum init [directory]

The init task initializes a new Serum project into the given directory. If the target directory does not exist, that directory will be automatically created. If the target directory already exists and is not empty, Serum will refuse to create a new project. Use -f (--force) option to create a new project anyway.

If the directory argument is not passed, Serum will try to initialize a new project into your current working directory.

Options

  • -f or --force
    Forces the initialization of new project on a non-empty directory.

build — Builds a Project

% serum build [-p|--parallel] [(-o|--output) <outdir>] [directory]

The build task builds your Serum project into a complete website. The directory argument should point at a valid Serum project directory. This argument may be ignored, in this case you need to be in (i.e, the PWD must be set to) a valid Serum project directory.

Options

  • -p or --parallel
    Basically Serum builds all pages one by one sequentially. If this option is provided, Serum will perform a parallel build by launching one build process per a page at the same time.
  • -o <outdir> or --output <outdir>
    The output directory of your website can be set by using this option. It is recommended to point to an empty directory, because all existing files or directories will be deleted without any warning or a question. If this option is not supplied, Serum will build the website into </path/to/project>/site directory by default.

    NOTE

    Hidden files starting with '.' are preserved, as they may contain important data, such as Git repository information.

server — The Serum Development Server

% serum server [(-p|--port) <port>] [directory]

The server task builds your Serum project and starts the development server. Like the build task, the optional directory option should be a valid Serum project directory. The website will be built into a temporary directory under /tmp, and will be removed when the server quits.

Options

  • -p <port> or --port <port>
    By default, the Serum development server listens on port 8080. If that port is unavailable or you need to use the other port, you can override that by using this option.

Server Commands

Once the development server has successfully started, you can interact with the server by typing commands. Available commands are:

  • build — Rebuilds current project.
  • quit — Stops the development server and quit.
NOTE

Please make sure you type the quit command to stop the development server. Pressing Control-C causes unclean exit, leaving the temporary directory not removed.

help — Shows the Help Message

% serum help [task]

If executed without any argument, the help task prints summary of all tasks. If you want to read detailed explanation about a specific task, give the name of the task as an argument (e.g. serum help build).

Exit Status

The command-line program reports one of these exit status code depending on the result of the task:

  • 0 — The task has been completed normally.
  • 1 — An error occurred while running the task.
  • 2 — There is a problem in the command-line argument.