soupault

Initialize a minimal website project in the current working directory

$ soupault --init

$ soupault

$ soupault --config [config_path] --site-dir [input_dir] --build-dir [output_dir]

$ soupault --index-only --dump-index-json [path/to/file.json]

$ soupault --show-effective-config

soupault [OPTIONS]

-h, --help
    Show the help message and exit.

-v, --version
    Print version information and exit.

-c <file>, --config <file>
    Specify an alternative configuration file. The default is soupault.conf.

-o <dir>, --output-dir <dir>
    Specify the output directory for generated files. The default is _site.

-s <dir>, --site-dir <dir>
    Specify the input directory for source files. The default is the current directory (.).

-w, --watch
    Watch for file changes in the input directory and rebuild the site automatically.

-e, --force-external-deps
    Force recompilation of Lua plugins if their external dependencies change.

-l <level>, --log-level <level>
    Set the log level (e.g., info, debug, warning, error).

--init
    Initialize a new soupault project in the current directory, creating a default configuration file.

--build-only-page <file>
    Only build a specific page from the input directory.

--no-dump-full-config
    Do not dump the full configuration to standard error during execution.

--no-pretty-print-html
    Disable pretty-printing of the HTML output, resulting in more compact files.

--strict
    Abort execution on non-critical errors, enforcing stricter error handling.

soupault is a flexible static site generator written in OCaml, primarily designed for transforming and enhancing existing HTML files. Unlike many traditional static site generators that focus on creating content from templates, soupault operates on the principle of HTML tree manipulation.

It allows users to select specific HTML elements using CSS selectors and apply various operations such as content insertion, attribute modification, element removal, and reordering. Its power stems from its highly configurable soupault.conf file, which defines the rules for these transformations. Furthermore, it supports embedding Lua scripts for more complex, programmatic content generation or manipulation, making it a powerful tool for sophisticated website builds or for adding dynamic-like features to static content. It is particularly useful for incrementally adding features to existing HTML-based sites without requiring a full rewrite.

soupault relies heavily on CSS selectors; familiarity with them is crucial for effective configuration. While powerful, extensive Lua scripting can introduce complexity if not carefully managed. It is important to note that soupault is not a full-fledged templating engine like Jinja2 or Liquid; its primary focus is on HTML post-processing and transformation.

The core of soupault's operation is its declarative configuration file, soupault.conf, typically written in TOML format. This file defines a series of "rules" that specify which HTML elements to target (using CSS selectors) and what transformations to apply to them. Rules can range from simple content replacement to more complex operations involving external files, Markdown conversion, or embedded Lua scripts. This declarative approach makes site transformations highly manageable and auditable.

soupault allows embedding Lua scripts directly within the configuration file or as external files. This provides a powerful mechanism for highly custom and dynamic content generation or manipulation that goes beyond the capabilities of the declarative rules. Lua scripts can interact with the HTML document tree, access configuration variables, perform arbitrary computations, and integrate with external data sources, offering immense flexibility for complex site builds.

Unlike many static site generators that primarily process Markdown or other text formats into HTML via templates, soupault primarily works by parsing existing HTML files into an Abstract Syntax Tree (AST) and then applying transformations directly to this tree. This makes it exceptionally well-suited for modifying, enriching, or restructuring HTML content that might have been generated by other tools, existing CMS exports, or created manually, providing a unique 'post-processing' capability.

soupault was created by Vladimir Panteleev (dmb) and first released around 2018. Its development was motivated by a desire for a static site generator that focused on HTML transformation rather than pure templating. This approach aimed to provide greater flexibility in modifying existing HTML structures, making it easier to add features or standardize elements across a site without requiring a complete content rewrite into a specific templating language. It has gained popularity for its unique HTML-centric approach and its extensibility via Lua scripting.

jekyll(1), hugo(1), make(1), pandoc(1)