The main command
All Kalenuxer operations are invoked through a single entry point:
node run.js <website-name> <action> <mode> [flags]
| Argument | Required | Description |
|---|---|---|
website-name | Yes | The name of the site directory under websites/ that you want to build. |
action | Yes | What pipeline action to run. Use prepare for a full build. |
mode | Yes | Build mode: release for production or debug for development. |
-unsafe | No | Skip FTP and deployment errors so the local build still completes. |
Build modes
Kalenuxer supports two build modes that control how output assets are processed:
| Mode | CSS / JS | Use when |
|---|---|---|
release | Minified and versioned with content hashes | Preparing a production deployment |
debug | Unminified, readable source output | Local development and debugging |
In release mode, all CSS and JS files are minified and given a content-based hash in their filename (e.g. main.abc123.css). This ensures browsers always receive fresh assets after a deploy without requiring manual cache busting.
Actions
The prepare action runs the complete build pipeline from start to finish. The pipeline stages execute in order:
Plugins and icons
Third-party plugins are initialized and icon fonts are processed via Gulp into the output directory.
CSS processing
Source stylesheets from site/css/ are minified, versioned, and written to dist/. Only modified files are reprocessed.
JS processing
Source scripts from site/js/ are minified, versioned, and written to dist/. Only modified files are reprocessed.
Image optimisation
PNG, JPEG, and WebP images are optimised and written to dist/.
HTML templates and pages
Template includes are resolved, variables are substituted from JSON data files, and HTML pages are written to dist/. Each language is processed independently.
Deployment (optional)
If FTP configuration is present, the built output is uploaded to the remote server. Use the -unsafe flag to skip this stage when building locally.
Forcing a full rebuild
Kalenuxer tracks file modification times in store/times/ to enable incremental builds. To force a specific asset type to be fully rebuilt, overwrite the corresponding timestamp file with an empty JSON object before running the build:
echo {} > store/times/release/css.jsonecho {} > store/times/release/js.jsonecho {} > store/times/release/html.jsonAfter writing the empty object, run your normal build command. All files of that type will be processed regardless of their modification time. This is useful when you change configuration that affects output but does not touch the source files themselves.
The -unsafe flag
When no FTP or remote deployment server is configured, the build pipeline will throw an error at the upload stage. Adding the -unsafe flag instructs the pipeline to swallow these errors and complete the rest of the build:
node run.js my-site prepare release -unsafe
This is the recommended flag to use when building locally for development. It does not affect the quality or completeness of the output in dist/ — it only skips the remote upload step.
Asset manifest
The file datas/html.json is the asset manifest. It maps logical asset names to the versioned physical file paths that the build has written to dist/. HTML templates reference assets using a logical injection syntax rather than hardcoded filenames:
<script src="{js:main:pages:home}"></script><link rel="stylesheet" href="{css:main:pages:home}">The build resolves these placeholders to the actual versioned paths recorded in datas/html.json at build time. This keeps HTML templates decoupled from physical file names and ensures version changes propagate automatically.
dist/. Every build pass rewrites the output directory. Any manual changes will be lost on the next build run.