Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

zola-bin

U-C-S50MIT1.0.0TypeScript support: included

Zola, A Static Site Generator, as a NPM Package

zola, tera, static-site-generator, ssg, markdown, rust, html, scss, sass, bin, cli, front-end, framework

readme

zola-bin

npm npm GitHub release (latest SemVer)

What is Zola ?

Zola is a static site generator (SSG), similar to Hugo, Pelican, and Jekyll. It is written in Rust and uses the Tera template engine, which is similar to Jinja2, Django templates, Liquid, and Twig. Content is written in CommonMark, a strongly defined, highly compatible specification of Markdown.

This repository provides the zola binary wrapper and the create-zola-site script as NPM packages.

Why Zola as a NPM package ??

This package provides Node.js bindings for Zola, compiled directly from its source code and exposed via Node-API or standard JavaScript calls. This approach ensures performance close to that of native binaries while offering the convenience of an npm package, making deployment easier across various environments due to Node.js' extensive ecosystem and support.

Usage

Add it as a dependency into your project or a new one, using....

npm i zola-bin

or

npm i -g zola-bin

From CLI

Format: zola-bin [args]

args are same as official zola CLI. Additionally, In your project's package.json file, you call it inside a script after adding it as a devDependency.

"scripts": {
    "dev": "zola-bin serve --port 7000 --open",
    "build": "zola-bin build"
}

JavaScript API

import zola, { execZola, getZolaPath } from "zola-bin";

execZola([....args]); // same as calling zola-bin [args] from command line

Following methods are just a wrapper around execZola.

Check out for usage - https://www.getzola.org/documentation/getting-started/cli-usage

interface buildOps {
    base_url?: string;
    output_dir?: string;
    config_file?: string;
}
interface serveOps extends buildOps {
    open?: boolean;
    port?: number;
    interface?: string;
}

declare const zola: {
    build(options?: buildOps): void;

    serve(options?: serveOps): void;

    check(): void;

    init(name?: string): void;
};

export default zola;

Getting Started with Create Zola Site

With NPM installed, you can quickly setup a new Zola site with the following command:

npx create-zola-site -n {NAME}

This will create a new directory {NAME} and initializes the necessary files in it. Note that the site created using this process depends on Node.js, so you might see package.json and node_modules in the directory. This doesn't mean it any works different than actual template initialized by Zola. But This template will simplify the process of creating, building and deploying a new site.

if you already have a existing site, you can add the zola-bin NPM package to make it work same as the one created with create-zola-site.

npm init
npm i -D zola-bin

And then you can add the following script to your package.json file:

"scripts": {
    "dev": "zola-bin serve --open",
    "build": "zola-bin build",
}

FAQ

  • What is the difference between Zola and create-zola-site template ?

    • Nothing, directory structure is pretty much the same and works the same.
    • create-zola-site template creates extra files - package.json and node_modules, with zola-bin npm package as a devDependency, which builds bindings from the source code and exposes them as node.js function calls.
  • Why would I use this instead of the official one ?

    • Because for few who are used to NPM, this package makes it feel more like its a part of NPM ecosystem.
    • Easyily deploy the sites since Node.js and NPM are accepted by most of the hosting services.
    • Simple installation and usage.

changelog

1.0.0 (2025-02-09)

  • Use Node-API and napi-rs to build native bindings for zola
  • Update CI to adapt to new build process
  • [BREAKING] Remove direct usage of zola binaries and getZolaPath fn

0.3.7 (2023-04-02)

  • Update zola version to v0.17.2

0.3.6 (2023-02-25)

  • Update zola version to v0.17.1 (no v0.17.0)
  • Support env variables in script update zola to next version by @kogeletey in #20
  • Other minor fixes/updates with scripts in tests, getzola.js

0.3.5 (2022-08-16)

  • Fix the Github Action publishing zola-bin platform deps without bin file

0.3.4 (2022-08-16) (YANKED)

  • Update zola to v0.16.1 (#2)

0.3.3 (2022-01-26)

  • Update zola to v0.15.3
  • Use specific versions of zola-bin-* in the package.json optionalDependencies, instead of latest
  • Update README.md

0.3.2 (2022-01-12)

  • support node >v14 (prev, >v16)
  • (internal) seperate zola object from lib\exec to lib\zola

0.3.1 (2022-01-10)

  • minor logic fixes
  • updates to documentation

0.3.0 (2022-01-09)

  • support for env variable ZOLA_BIN_PATH
  • add easy to use methods - build, serve, check, init

0.2.1 (2021-12-31)

  • Error handling for zola binary file calls

0.2.0 (2021-12-24)

  • Remove async version of exec
  • Rename exec to execZola

0.1.0 (2021-12-23)

  • Update zola-bin-* packages to respective zola version (currently 0.15.2)
  • Add async and synchronous versions of exec function in zola-bin library
  • Migrate lib code to Typescript (which provides types for export automatically)

0.0.7 (2021-11-26)

  • Update package.json meta data
  • Add READMEs