Soupault Documentation

Soupault is an HTML manipulation tool that functions as either a static site generator or an HTML post-processor for existing websites. It operates on the HTML element tree, allowing for tasks like injecting new HTML into complete pages or generating tables of contents.

Unlike many static site generators, Soupault does not use front matter. Instead, it extracts metadata directly from HTML using CSS3 selectors. This allows it to index hand-written static pages as structured content.

Key features include:

• Extensibility: Supports page preprocessors (e.g., Markdown to HTML), asset processors (e.g., Sass/Less compilers), external program piping, and Lua plugins.
• Durability: Distributed as a statically-linked binary with no dependencies.
• Flexibility: Highly configurable via TOML, with page processing hooks and Lua plugin support.

Once metadata is extracted via index.fields, you can render it into specific parts of your site using index.views.

• index_selector: The CSS selector identifying the element in your HTML where the rendered content should be injected.
• index_item_template: A string containing HTML and placeholders (e.g., {{title}}, {{url}}, {{date}}, {{excerpt}}) that defines how each item in the index should look.

[index.views.blog]
  # Insert rendered data into the element that matches "#blog-index" CSS selector.
  index_selector = "#blog-index"
  index_item_template = """
    <h2><a href="{{url}}">{{title}}</a></h2>
    <p><strong>Last update:</strong> {{date}}.</p>
    <p>{{excerpt}}</p>
    <a href="{{url}}">Read more</a>
  """

You define how Soupault extracts metadata from your HTML by configuring index.fields in a TOML configuration file. You use CSS3 selectors to target specific elements.

Supported options for fields:

• selector: An array of CSS selectors to try in order.
• required: If true, the build will fail if the selector finds no match.
• extract_attribute: Specifies a specific attribute (e.g., datetime) to extract from an element.
• fallback_to_content: If true, if the specified attribute is missing, Soupault will use the element's text content instead.

# Post title
[index.fields.title]
  selector = ["h1#post-title", "h1"]
  required = true

# Post excerpt
[index.fields.excerpt]
  selector = ["p#post-excerpt", "p"]

# Post date
[index.fields.date]
  selector = ["time#post-date", "time"]
  extract_attribute = "datetime"
  fallback_to_content = true