Soupault

https://soupault.net
Admin
A static site generator project with comprehensive versioned documentation.
Tokens:71,098
Snippets:989
Trust Score:5.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Basic Widget Configuration Example

Source: https://soupault.net/tips-and-tricks/getting-started-html-processor

This example shows a TOML configuration with two widgets: 'set-title' and 'generator-meta'. It includes general site settings.

```toml
[settings]
  strict = false
  verbose = true

  generator_mode = false

  clean_urls = false

  build_dir = "build"
  site_dir = "site"

  doctype = "<!DOCTYPE html>"

  page_file_extensions = ["htm", "html"]

[widgets.set-title]
  selector = "h1"
  default = "My website"

[widgets.generator-meta]
  widget = 'insert_html'
  selector = 'head'
  html = '<meta name="generator" content="soupault">'

```

--------------------------------

### Enable Gentoo GURU Overlay and Install Soupault

Source: https://soupault.net/install

Install Soupault on Gentoo by enabling the GURU overlay, synchronizing repositories, and then emerging the package. Supports both source and binary packages.

```bash
eselect repository enable guru
emerge --sync
emerge www-apps/soupault  # or www-apps/soupault-bin
```

--------------------------------

### Install Soupault using OPAM

Source: https://soupault.net/install

Install Soupault from the OPAM repository if you have OCaml and OPAM installed. This is a straightforward command for OCaml developers.

```bash
opam install soupault
```

--------------------------------

### Inline Lua Plugin Example

Source: https://soupault.net/reference-manual

This configuration demonstrates how to add a simple inline Lua plugin directly into the configuration file.

```toml
[plugins.trivial-plugin]
  lua_source = 'Plugin.exit("this plugin cannot do much")'

```

--------------------------------

### Cross-Platform Configuration Example

Source: https://soupault.net/blog/windows

This configuration works on all systems, including Windows, for paths interpreted by Soupault itself. It sets a default template and includes a footer.

```ini
[settings]
default_template = 'templates/main.html'

[widgets.footer]
  widget = 'include'
  file = 'templates/footer.html'
  selector = 'body'

```

--------------------------------

### Soupault Build Logs

Source: https://soupault.net/tips-and-tricks/quickstart

Example output from running the 'soupault' command, showing processing messages for pages and widgets, including the newly added Quick Links widget.

```log
[INFO] Processing page site/my-first-post.md
[INFO] Calling preprocessor pandoc -f commonmark+smart -t html on page site/my-first-post.md
[INFO] Using the default template for page site/my-first-post.md
[INFO] Processing widget quick-links on page site/my-first-post.md
[INFO] Processing widget insert-sakura-css on page site/my-first-post.md
[INFO] Processing page site/index.html
[INFO] Using the default template for page site/index.html
[INFO] Inserting section index
[INFO] Rendering index view "blog" on page site/index.html
[INFO] Generating section index
[INFO] Processing widget quick-links on page site/index.html
[INFO] Processing widget insert-sakura-css on page site/index.html

```

--------------------------------

### Check String Starts With Prefix

Source: https://soupault.net/reference-manual

Determines if a string begins with a specified prefix.

```lua
String.starts_with("hello", "hell")
```

--------------------------------

### Serve Website Locally with Python HTTP Server

Source: https://soupault.net/blog/automation

Use this command to start a simple HTTP server from Python 3 to test your website locally. It serves files from the specified directory.

```bash
python3 -m http.server --directory $(BUILD_DIR)
```

--------------------------------

### Apply Widget to All Pages in a Section

Source: https://soupault.net/blog/limiting-widgets

Example configuration to apply a widget to all pages within the `blog/` directory. This uses the `section` option.

```toml
[widgets.some-widget]
  section = "blog/"

  ...

```

--------------------------------

### Front Matter Example

Source: https://soupault.net/blog/blogs-and-section-indices

A typical front matter structure used in static site generators for metadata.

```yaml
---
title: Why soupault?
date: 2019-10-10
---
There are many...

```

--------------------------------

### Deploy Site with rsync and SSH

Source: https://soupault.net/blog/automation

An example of deploying a website using rsync over SSH, suitable for self-hosted servers. It synchronizes the build directory with the remote web server directory.

```bash
rsync -a -e "ssh" $(BUILD_DIR)/ www.baturin.org:/var/www/vhosts/baturin.org
```

--------------------------------

### Post-Build Hook Example

Source: https://soupault.net/reference-manual

This snippet shows how to use the post-build hook to log the total number of pages in the site index. It accesses the `site_index` variable available in the post-build environment.

```lua
[hooks.post-build]
  lua_source = '''
    Log.debug("Number of pages in the site index: " .. (Table.length(site_index)))
  '''


```

--------------------------------

### Install Soupault with Musl and Static Linking on Linux

Source: https://soupault.net/reference-manual

Commands to set up an OCaml environment for building statically linked soupault executables for Linux using musl. This ensures compatibility across different Linux distributions.

```bash
# Install dependencies, for Fedora (or recent RHEL/CentOS Stream):
sudo dnf install musl-gcc musl-libc-static

# Install dependencies, for Debian:
sudo apt install musl musl-dev musl-tools

# Create an OCaml installation that uses musl-based runtime
opam switch create 5.4.0-musl ocaml-variants.5.4.0+options ocaml-option-musl ocaml-option-static
opam switch 5.4.0-musl

```

```bash
dune build --profile=static

```

--------------------------------

### Get Program Output with Input

Source: https://soupault.net/reference-manual

Runs an external command, providing input data to its stdin, and captures its stdout.

```lua
Sys.get_program_output("sort", "line1\nline3\nline2")
```

--------------------------------

### HTML Structure for Soupault Extraction

Source: https://soupault.net/blog/blogs-and-section-indices

Example of an HTML blog post beginning, with specific IDs for Soupault to target.

```html
<h1 id="post-title">Why soupault?</h1>

<span>Date: <time id="post-date">2019-10-10</time> </span>

<p id="post-excerpt">
There are so many static site generators already that another one needs a pretty good justification.
I mainly made soupault for my own use, in fact it has grown out of a set of custom scripts that used to power
the <a href="https://baturin.org">baturin.org</a> website. Still, if I'm making it public, I may as well want to
explain the decisions behing it and reasons why anyone else may want to use it.
</p>

```

--------------------------------

### Create a Markdown Post

Source: https://soupault.net/tips-and-tricks/quickstart

Example of a Markdown file with basic HTML content, including a time element and a paragraph for an excerpt. This file will be processed by Soupault.

```markdown
# My first post

<time id="post-date">1970-01-01</time>

This is an introductory paragraph. It’s long and only interesting for the really dedicated readers.
Everyone else will just skip it.

<p id="post-excerpt">
This is my first post in the brand new soupault blog. It’s really interesting, except for its
introductory paragraph of course. That one is boring and should never be displayed on the front page.
</p>

Well, I mean it would be interesting if there was any content in this post. Sadly, there isn’t,
so it’s no better than its introductory paragraph.

```

--------------------------------

### Element Template Environment Example

Source: https://soupault.net/reference-manual

Illustrates the data environment available to the 'element_template' widget when rendering a template. It includes element attributes and inner HTML.

```json
{
  "title": "Sintel",
  "content": "eRsGyueVLvQ"
}

```

--------------------------------

### GitHub Actions Workflow for Soupault Build

Source: https://soupault.net/tips-and-tricks/deployment

This YAML workflow installs Soupault, builds the site, and includes a placeholder for deployment steps. It uses a specific Ubuntu LTS runner and checks out the repository.

```yaml
jobs:
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - uses: actions/checkout@v2

    - name: Install soupault
      env:
        SOUPAULT_VERSION: 5.3.0$
      run: |
        echo Downloading and unpacking soupault
        wget https://github.com/PataphysicalSociety/soupault/releases/download/$SOUPAULT_VERSION/soupault-$SOUPAULT_VERSION-linux-x86_64.tar.gz
        tar xvf soupault-$SOUPAULT_VERSION-linux-x86_64.tar.gz
        sudo mv -v ./soupault-$SOUPAULT_VERSION-linux-x86_64/soupault /usr/bin/

    - name: Build the site
      run: |
        soupault

    # Your deployment steps here

```

--------------------------------

### Get All File Extensions

Source: https://soupault.net/reference-manual

Returns a list of all extensions for a file path. Returns an empty list if there are no extensions. For '.tar.gz', it returns {'tar', 'gz'}.

```lua
Sys.get_extensions("archive.tar.gz")
-- returns {"tar", "gz"}
Sys.get_extensions("image.jpeg")
-- returns {"jpeg"}
Sys.get_extensions("no_extension")
-- returns {}
Sys.get_extensions(".bashrc")
-- returns {}
```

--------------------------------

### Configure a Custom Widget

Source: https://soupault.net/reference-manual

Configure a custom widget by defining its type and selector within the `[widgets]` table. This example shows a hypothetical 'frobnicator' widget.

```toml
[widgets.frobnicate]
  widget = "frobnicator"
  selector = "div#frob"

```

--------------------------------

### Configure Markdown Preprocessor

Source: https://soupault.net/reference-manual

Specify an external program to preprocess Markdown files before Soupault processes them. This example uses 'cmark' for Markdown conversion.

```toml
[preprocessors]
  md = "cmark --unsafe --smart"

```

--------------------------------

### Initialize a Basic Soupault Project

Source: https://soupault.net/tips-and-tricks/faq

Run this command in an empty directory to create the default project structure, including configuration, site content, and template files.

```bash
soupault --init
```

--------------------------------

### Get Last File Extension

Source: https://soupault.net/reference-manual

Returns the last extension of a file path. Returns an empty string if there are no extensions. Handles multiple extensions like '.tar.gz' by returning only the last one ('gz'). Files starting with a dot (like '.bashrc') are considered to have no extension.

```lua
Sys.get_extension("archive.tar.gz")
-- returns "gz"
Sys.get_extension("document.pdf")
-- returns "pdf"
Sys.get_extension("Makefile")
-- returns ""
Sys.get_extension(".config")
-- returns ""
```

--------------------------------

### Render Hook: Pretty-Print HTML

Source: https://soupault.net/reference-manual

The render hook runs instead of the built-in page rendering. This example demonstrates how to pretty-print the generated HTML.

```lua
page_source = soupault_config["settings"]["doctype"] .. "\n" .. HTML.pretty_print(page)
```

--------------------------------

### Configure Inline Styles Plugin

Source: https://soupault.net/plugins

Move CSS from <inlineStyle> elements in the page body to <style> elements in the head. This example shows how to set a pink background for a specific page.

```toml
[widgets.inline-styles]
  widget = "inline-styles"

```

```html
<inlineStyle>
body { background: pink }
</inlineStyle>

```

--------------------------------

### Create Project Directories

Source: https://soupault.net/tips-and-tricks/quickstart

This command sequence sets up the necessary directories for a Soupault project: 'site' for content, 'templates' for page templates, and 'plugins' for extensions.

```bash
cd my-blog
mkdir site/
mkdir templates/
mkdir plugins/

```

--------------------------------

### Configure Asset Processor for PNG Files

Source: https://soupault.net/reference-manual

Define an asset processor to optimize PNG files using `pngcrush`. This example shows how to specify the command and available template variables for file paths and names.

```toml
[asset_processors]
  png = "pngcrush {{source_file_path}} {{target_dir}}/{{source_file_name}}"

```

--------------------------------

### Lua Index Processor Example

Source: https://soupault.net/reference-manual

This Lua script reimplements the built-in index_template behavior and creates a clone of the index page. Generated pages are stored in the 'pages' variable.

```lua
-- Render entries on the page
env = {}
env["entries"] = site_index
rendered_entries = HTML.parse(String.render_template(config["index_template"], env))
container = HTML.select_one(page, config["index_selector"])
HTML.append_child(container, rendered_entries)

-- Make a clone of the blog index page and add it to the generated page list.
-- Soupault will extract the `pages` variable from the Lua environment
-- when this script finishes.
pages = {}
pages[1] = {}
pages[1]["page_file"] = Sys.join_path(Sys.dirname(page_file), "index_clone.html")
pages[1]["page_content"] = HTML.pretty_print(page)

```

--------------------------------

### Preprocess Element Content with External Commands

Source: https://soupault.net/

Use the 'preprocess_element' widget to pipe element content through an external program. This example highlights source code using the 'highlight' tool, dynamically selecting the syntax based on the element's class attribute.

```toml
# Runs the content of <* class="language-*"> elements through a syntax highlighter
[widgets.highlight]
  widget = "preprocess_element"
  selector = '*[class^="language-"]'
  command = 'highlight -O html -f --syntax=$(echo $ATTR_CLASS | sed -e "s/language-//")'

```

--------------------------------

### Download Quick Links Plugin

Source: https://soupault.net/tips-and-tricks/quickstart

Use these commands to create a plugins directory and download the Quick Links Lua plugin.

```bash
$ mkdir plugins/
$ wget https://soupault.net/files/plugins/quick-links.lua -O plugins/quick-links.lua

```

--------------------------------

### Get URL basename

Source: https://soupault.net/reference-manual

Sys.basename_url is an alias for Sys.basename_unix, providing a consistent way to get the basename for URLs.

```lua
Sys.basename_url(file_path)
```

--------------------------------

### Python Echo Script Example

Source: https://soupault.net/reference-manual

A simple Python script demonstrating how an external program should read all input from stdin at once, process it, and then write the result to stdout. This avoids deadlocks with Soupault.

```python
import sys

input = sys.stdin.read()
print(input)
```

--------------------------------

### Get href Attribute from Link

Source: https://soupault.net/reference-manual

This snippet demonstrates how to get the 'href' attribute value from a selected link element.

```lua
href = HTML.get_attribute(link, "href")

```

--------------------------------

### Define Page File Extensions

Source: https://soupault.net/reference-manual

Specify which file extensions Soupault should treat as page files. This example sets 'html' and 'htm' as the default page file extensions.

```toml
[settings]
  page_file_extensions = ["html", "htm"]

```

--------------------------------

### Get Table Keys

Source: https://soupault.net/reference-manual

Returns a list of all keys present in the table.

```lua
Table.keys(table)
```

--------------------------------

### Serve Site with Python HTTP Server

Source: https://soupault.net/tips-and-tricks/quickstart

Use Python's built-in HTTP server to serve the generated static site from the 'build/' directory. This is a quick way to preview your site locally.

```bash
$ python3 -m http.server --directory build
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
```

--------------------------------

### Configure Soupault Plugin

Source: https://soupault.net/blog/enhancing-existing-website

Example TOML configuration for the 'insert-index' widget plugin. Use 'exclude_page' to prevent execution on specific pages and 'after' to control execution order. The 'selector' option is available to the plugin as config["selector"].

```toml
[widgets.insert-index]
  after = "insert-index-container"
  exclude_page = ["index.html", "updates/index.html", "about/index.html", "buttons/index.html"]
  widget = "alphabetic-index"

  # Available to the plugin as config["selector"]
  selector = "div#index"
```

--------------------------------

### Get Unix-style basename

Source: https://soupault.net/reference-manual

Use Sys.basename_unix for path manipulation that requires forward slashes, such as with URLs.

```lua
Sys.basename_unix(file_path)
```

--------------------------------

### Create Build Configuration File

Source: https://soupault.net/tips-and-tricks/deployment

Create the .build.yml file in your project directory to define the build environment.

```bash
$ touch .build.yml
```

--------------------------------

### Build Website with Soupault

Source: https://soupault.net/tips-and-tricks/quickstart

This command initiates the website build process using Soupault. With verbose mode enabled in the configuration, it will display progress information during the build.

```bash
$ soupault
[INFO] Build directory "build" does not exist, creating
[INFO] Processing page site/index.html
[INFO] Using the default template for page site/index.html

```

--------------------------------

### Get File Modification Time

Source: https://soupault.net/reference-manual

Returns the UNIX timestamp of the last modification time for a file.

```lua
Sys.get_file_modification_time("report.txt")
```

--------------------------------

### Get Environment Variable

Source: https://soupault.net/reference-manual

Retrieves the value of an environment variable. Returns a default value if the variable is not set.

```lua
Sys.getenv("PATH", "/usr/bin")
```

--------------------------------

### Build Site with Soupault

Source: https://soupault.net/tips-and-tricks/quickstart

Run the Soupault command to build the static site. This command will process pages, apply widgets like CSS insertion, and generate the output in the 'build/' directory.

```bash
$ soupault
[INFO] Processing page site/index.html
[INFO] Using the default template for page site/index.html
[INFO] Processing widget insert-sakura-css on page site/index.html
```

--------------------------------

### Get List of HTML Element Attributes

Source: https://soupault.net/reference-manual

Returns a list of all attribute names for a given HTML element.

```lua
HTML.list_attributes(html_element)
```

--------------------------------

### Get Table Key with Default Value

Source: https://soupault.net/reference-manual

Returns the value associated with the key, or a default value if the key is not found.

```lua
Table.get_key_default(table, key, default_value)
```

--------------------------------

### Configure Source Directory (Windows)

Source: https://soupault.net/tips-and-tricks/getting-started-html-processor

Set the `site_dir` option to point to your existing website's source directory on Windows.

```toml
[settings]
  site_dir = 'C:\\Users\\jrandomhacker\\homepage'
```

--------------------------------

### Plugin communication: Get Soupault version

Source: https://soupault.net/reference-manual

Plugin.soupault_version returns the version string of the currently running Soupault instance.

```lua
Plugin.soupault_version()
```

--------------------------------

### Configure Source Directory (Linux/macOS)

Source: https://soupault.net/tips-and-tricks/getting-started-html-processor

Set the `site_dir` option to point to your existing website's source directory on Linux or macOS.

```toml
[settings]
  site_dir = '/home/jrandomhacker/homepage'
```

--------------------------------

### Get URL directory name

Source: https://soupault.net/reference-manual

Sys.dirname_url is an alias for Sys.dirname_unix, ensuring consistent directory name extraction for URLs.

```lua
Sys.dirname_url(file_path)
```

--------------------------------

### Get directory name

Source: https://soupault.net/reference-manual

Sys.dirname returns the directory portion of a path using OS-specific separators. Avoid for URLs.

```lua
Sys.dirname(file_path)
```

--------------------------------

### Download Sakura CSS Framework

Source: https://soupault.net/tips-and-tricks/quickstart

Download the Sakura CSS framework using wget to the 'site/' directory. Soupault will automatically copy it to the build directory as it has a .css extension.

```bash
wget https://raw.githubusercontent.com/oxalorg/sakura/master/css/sakura.css -O site/sakura.css
```

--------------------------------

### Configure Quick Links Widget

Source: https://soupault.net/plugins

This is a sample TOML configuration for the `quick-links` widget, which processes various social media and web links.

```toml
[widgets.convert-quick-links]
  widget = "quick-links"
  wikipedia_default_language = "fr"

```

--------------------------------

### Get HTML Element Inner Text

Source: https://soupault.net/reference-manual

Retrieves the content of an HTML element as a string, stripping all HTML tags.

```lua
HTML.inner_text(html)
```

--------------------------------

### Create Directory

Source: https://soupault.net/reference-manual

Creates a directory. If intermediate directories are missing, they will be created as well (similar to `mkdir -p`).

```lua
Sys.mkdir("output/results")
```

--------------------------------

### Get HTML Element Inner HTML

Source: https://soupault.net/reference-manual

Retrieves the content of an HTML element as a string, including any nested tags.

```lua
h = HTML.inner_html(HTML.select(page, "body"))
```

--------------------------------

### Get List of HTML Element Classes

Source: https://soupault.net/reference-manual

If an element has a 'class' attribute, this function returns a list of its individual classes.

```lua
HTML.get_classes(html_element)
```

--------------------------------

### Enable Caching and Set Cache Directory

Source: https://soupault.net/reference-manual

Configure Soupault to cache preprocessor and command outputs to speed up builds. The cache directory can be explicitly set; otherwise, it defaults to `.soupault-cache`.

```toml
[settings]
  # Enable caching
  caching = true

  # Optionally, change the cache directory
  # The default is `.soupault-cache`
  cache_directory = ".soupault-cache"

```

--------------------------------

### Create Project Directory

Source: https://soupault.net/tips-and-tricks/getting-started-html-processor

This command creates a new directory for your Soupault project.

```bash
$ mkdir mysite
```

--------------------------------

### Wrapper Selector Error Example

Source: https://soupault.net/reference-manual

This error occurs when a wrapper has multiple child elements and no wrapper selector is specified.

```text
[ERROR] Could not process page site/reference-manual.md: the wrapper has more then one child element but the wrapper selector is not specified

```

--------------------------------

### Get Unix-style directory name

Source: https://soupault.net/reference-manual

Use Sys.dirname_unix for directory name extraction that requires forward slashes, suitable for URLs.

```lua
Sys.dirname_unix(file_path)
```

--------------------------------

### Inline CSS with Highlight

Source: https://soupault.net/tips-and-tricks/static-rendering

Demonstrates using the 'highlight' command to output HTML with inline CSS styles. This method is generally not recommended for production due to larger file sizes and difficulty in style management.

```bash
$ echo "<p>foo</p>" | highlight --style matrix --syntax=html -O html  -f --inline-css
<span style="color:#55ff55; font-weight:bold">&lt;p&gt;</span>foo<span style="color:#55ff55; font-weight:bold">&lt;/p&gt;</span>

```

--------------------------------

### Get Directory Name of Path

Source: https://soupault.net/reference-manual

Returns the directory part of a path. Uses OS-specific separators. For URLs, use `Sys.dirname_url`.

```lua
Sys.dirname("/usr/local/bin/soupault") -- returns "/usr/local/bin"
Sys.dirname("file.txt") -- returns ""
```

--------------------------------

### Preview Processed Site with Python HTTP Server

Source: https://soupault.net/tips-and-tricks/getting-started-html-processor

Use Python's built-in HTTP server to preview the processed site from the build directory.

```bash
python3 -m http.server --directory build
```

--------------------------------

### Get File Size

Source: https://soupault.net/reference-manual

Returns the size of a file in bytes. Returns nil if the file cannot be accessed due to non-existence or permissions.

```lua
Sys.get_file_size("data.bin")
```

--------------------------------

### Include Widget Configuration

Source: https://soupault.net/blog/configurable-options

This snippet shows how to configure the 'include' widget. Ensure the specified file exists to avoid build errors when `strict` is enabled.

```toml
[widgets.footer]
  widget = "include"

  # file doesn't exist yet
  file = "templates/footer.html"
  selector = "div#footer"

```

--------------------------------

### Sys.strip_extensions

Source: https://soupault.net/reference-manual

Removes all extensions from a file name. For example, the result of `Sys.strip_extensions("foo.png")` is `"foo"`.

```APIDOC
## Sys.strip_extensions(path)

### Description
Removes all extensions from a file name. For example, the result of `Sys.strip_extensions("foo.png")` is `"foo"`.

### Method
GET (conceptual)

### Endpoint
`/sys/strip_extensions` (conceptual)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file.

### Request Example
```json
{
  "path": "archive.tar.gz"
}
```

### Response
#### Success Response (200)
- **path_without_extensions** (string) - The file path with all extensions removed.
```

--------------------------------

### Basic Soupault Configuration

Source: https://soupault.net/reference-manual

This snippet shows essential configuration settings for Soupault, including enabling plugin discovery, defining plugin directories, and managing output caching.

```toml
plugin_discovery = true
plugin_dirs = ["plugins"]

caching = true
cache_dir = ".soupault-cache"

page_character_encoding = "utf-8"
```

--------------------------------

### Get Current UNIX Timestamp

Source: https://soupault.net/reference-manual

Retrieve the current UNIX timestamp (seconds since 1970-01-01 00:00 UTC) using Date.now_timestamp().

```lua
Date.now_timestamp()
```

--------------------------------

### Basic Sourcehut Build Configuration

Source: https://soupault.net/tips-and-tricks/deployment

This configuration specifies the NixOS image, necessary packages (including Soupault), and environment variables for the build. It defines a 'build' task to run Soupault within the repository.

```yaml
image: nixos/unstable # at the time of writing, soupault only available in unstable 
packages:
  - nixos.soupault
  # … any additional dependencies (e.g. preprocessors)
  # - nixos.asciidoctor
environment:
  repo_name: "$YOUR_SOURCEHUT_REPOSITORY_NAME"
tasks:
  - build: |
    cd "$repo_name"
    soupault
  # add other tasks such as deployment via `curl`

```

--------------------------------

### Run External Program and Get Exit Code

Source: https://soupault.net/reference-manual

Executes an external command and returns its exit code. Does not capture stdout or stderr.

```lua
Sys.run_program_get_exit_code("grep pattern file.txt")
```

--------------------------------

### Get Base Name of Path

Source: https://soupault.net/reference-manual

Returns the file name part of a path. Uses OS-specific separators. For URLs, use `Sys.basename_url`.

```lua
Sys.basename("/usr/local/bin/soupault") -- returns "soupault"
Sys.basename("C:\\Users\\file.txt") -- returns "file.txt"
```

--------------------------------

### Build Site with Markdown Post

Source: https://soupault.net/tips-and-tricks/quickstart

Run the Soupault command to build the site after adding a Markdown post. The output shows the processing of the Markdown file using the configured Pandoc preprocessor.

```bash
$ soupault
[INFO] Processing page site/my-first-post.md
[INFO] Calling preprocessor pandoc -f commonmark+smart -t html on page site/my-first-post.md
[INFO] Using the default template for page site/my-first-post.md
[INFO] Processing widget insert-sakura-css on page site/my-first-post.md
[INFO] Processing page site/index.html
[INFO] Using the default template for page site/index.html
[INFO] Processing widget insert-sakura-css on page site/index.html
```

--------------------------------

### Get Tag Name of Selected Element

Source: https://soupault.net/reference-manual

This snippet shows how to select an element that is either an 'a' or 'img' tag and then retrieve its tag name.

```lua
link_or_pic = HTML.select_any_of(page, {"a", "img"})
tag_name = HTML.get_tag_name(link_of_pic)

```

--------------------------------

### Build Soupault from Source

Source: https://soupault.net/install

Clone the Soupault repository and pin the local source code using OPAM to build from source. Requires OCaml compiler (4.13+) and OPAM.

```bash
$ git clone <url>
$ cd soupault
$ opam pin add .
```

--------------------------------

### Use Wikipedia Tag in HTML

Source: https://soupault.net/tips-and-tricks/quickstart

Embed the custom <wikipedia> tag in your HTML to dynamically generate links, for example, to a Wikipedia page.

```html
<h1>Welcome to my <wikipedia>blog</wikipedia>!</h1>
<p>It’s still under construction, remember to check again later.</p>

<div id="blog-index"> </div>

```

--------------------------------

### Netlify Build Script for Soupault

Source: https://soupault.net/tips-and-tricks/deployment

This shell script downloads and unpacks the Soupault executable, then runs it to build the site. Ensure the SOUPAULT_VERSION variable is set correctly.

```shell
#!/bin/sh

SOUPAULT_VERSION="5.3.0$"

wget https://github.com/PataphysicalSociety/soupault/releases/download/$SOUPAULT_VERSION/soupault-$SOUPAULT_VERSION-linux-x86_64.tar.gz
if [ $? != 0 ]; then
    echo "Error: failed to download soupault."
    exit 1
fi

tar xvf soupault-$SOUPAULT_VERSION-linux-x86_64.tar.gz

./soupault-$SOUPAULT_VERSION-linux-x86_64/soupault

```

--------------------------------

### Create a header file

Source: https://soupault.net/tips-and-tricks/getting-started-html-processor

This command creates a simple HTML file named 'header.html' to be included in other pages.

```bash
echo "Please read: a personal appeal from the webmaster" > header.html
```

--------------------------------

### Deploy Site with Neocities CLI

Source: https://soupault.net/blog/automation

This command uses the Neocities CLI tool to push the contents of the build directory to your Neocities site.

```bash
neocities push $(BUILD_DIR)
```

--------------------------------

### Plugin communication: Get global data

Source: https://soupault.net/reference-manual

Plugin.get_global_data retrieves a piece of global data associated with the given key, shared across plugins.

```lua
Plugin.get_global_data(key)
```

--------------------------------

### Initial Soupault Configuration

Source: https://soupault.net/tips-and-tricks/quickstart

This TOML configuration sets up essential parameters for Soupault, including build directories, file extensions, template and content selectors, and HTML formatting options. It enables strict mode and verbose output for development.

```toml
[settings]
  # Stop on page processing errors?
  strict = true

  # Display progress?
  verbose = true

  # Display detailed debug output?
  debug = false

  # Where input files (pages and assets) are stored.
  site_dir = "site"

  # Where the output goes
  build_dir = "build"

  # Files with other extensions are considered static assets
  # and copied to build/ unchanged.
  page_file_extensions = ["htm", "html", "md", "rst", "adoc"]

  # Files with these extensions are ignored.
  ignore_extensions = ["draft"]

  # Treat files as content to insert in the template,
  # unless they have an <html> element in them.
  generator_mode = true
  complete_page_selector = "html"

  # Use templates/main.html file for the page template.
  default_template_file = "templates/main.html"

  # The content will be inserted into its <main> element,
  # after its last already existing child.
  default_content_selector = "main"
  default_content_action = "append_child"

  # Set the document type to HTML5, unless the page already has
  # a doctype declaration.
  doctype = "<!DOCTYPE html>"
  keep_doctype = true

  # Indent HTML tags for readability
  pretty_print_html = true

  # Translate site/about.html to build/about/index.html
  # If set to false, then site/about.html will become build/about.html
  clean_urls = true

  # Look for plugin files in plugins/
  plugin_discovery = true
  plugin_dirs = ["plugins"]

```

--------------------------------

### Get environment variable with default

Source: https://soupault.net/reference-manual

Sys.getenv retrieves an environment variable's value. If the variable is not set, it returns the provided default_value or nil.

```lua
Sys.getenv(name, default_value)
```

--------------------------------

### Get HTML Headings Tree Structure

Source: https://soupault.net/reference-manual

Returns a table representing the hierarchical structure of headings in an HTML document, suitable for ToC generation.

```lua
HTML.get_headings_tree(element)
```

--------------------------------

### GNU Make Makefile for Website Automation

Source: https://soupault.net/blog/automation

This Makefile defines targets for building the site with Soupault, copying assets, cleaning the build directory, serving the site locally, and deploying it. It uses variables for the build directory and the Soupault executable.

```makefile
BUILD_DIR := build

# In practice it's in my ~/.local/bin
SOUPAULT := soupault

.PHONY: site
site:
	$(SOUPAULT)

.PHONY: assets
assets:
	cp -r assets/* $(BUILD_DIR)/

.PHONY: all
all: site assets

.PHONY: clean
clean:
	rm -rf $(BUILD_DIR)/*

.PHONY: serve
serve:
	python3 -m http.server --directory $(BUILD_DIR)

.PHONY: deploy
deploy:
	neocities push $(BUILD_DIR)

```

--------------------------------

### Index View Configuration with Python Processor

Source: https://soupault.net/reference-manual

Configures an index view named 'blog-summary' to use a Python script for processing and to target the 'blog/' section.

```ini
[index.views.blog-summary]
  section = "blog/"
  index_processor = "scripts/blog-summary.py"

```

--------------------------------

### Run Soupault Processor

Source: https://soupault.net/tips-and-tricks/getting-started-html-processor

Navigate to your project directory and run the `soupault` command to process your HTML files.

```bash
$ cd mysite
$ soupault
```

--------------------------------

### Generated HTML with Class Levels

Source: https://soupault.net/blog/toc

Example of the HTML output generated by Soupault when `toc_class_levels` is enabled, showing distinct classes for each list level.

```html
<ul class="toc-1">
  <li> <a href="#chapter-1">Chapter 1</a> </li>
  <ul class="toc-2">
    <li> <a href="#section-1">Section 1</a> </li>
    <ul class="toc-3">
      <li> <a href="#subsection-1">Subsection 1</a> </li>
    </ul>
 </ul>
</ul>

```

--------------------------------

### Override Configuration and Directories (Windows)

Source: https://soupault.net/reference-manual

Run Soupault with custom configuration and site directories using command-line options. The `--config` option is particularly useful on Windows.

```powershell
C:\> soupault --config mysite.toml --site-dir some-input-dir --build-dir some-other-dir

```

--------------------------------

### Override Soupault Configuration and Directories (Windows)

Source: https://soupault.net/tips-and-tricks/faq

Use command-line options to specify custom locations for the configuration file, site source directory, and build output directory on Windows.

```bash
soupault --config A:\mysite.cfg --site-dir B:\mysite --build-dir C:\inetpub\wwwroot\
```

--------------------------------

### Configure Multiple Plugin Directories

Source: https://soupault.net/reference-manual

This setting specifies multiple directories where Soupault should look for plugins.

```toml
[settings]
  plugin_dirs = ["plugins", "/usr/share/soupault/plugins"]

```

--------------------------------

### Add Footnotes

Source: https://soupault.net/tips-and-tricks/faq

Configure Soupault to manage footnotes on your pages. This setup assumes a specific div for footnotes and defines how footnotes and their back-links are handled.

```toml
[widgets.footnotes]
  widget = "footnotes"
  selector = "div#footnotes"
  footnote_selector = ".footnote"
  footnote_link_class = "footnote"
  back_links = true
  link_id_prepend = "footnote-"
  back_link_id_append = "-ref"

```

--------------------------------

### Execute system command and get exit code

Source: https://soupault.net/reference-manual

Sys.run_program_get_exit_code executes a command and returns its raw exit code, where 0 typically indicates success.

```lua
Sys.run_program_get_exit_code(command)
```

--------------------------------

### Include a file as a header

Source: https://soupault.net/tips-and-tricks/getting-started-html-processor

This configuration includes the 'header.html' file and prepends it as a child to the 'body' element, effectively creating a header.

```toml
[widgets.header]
  widget = 'include'
  selector = 'body'
  file = 'header.html'
  action = 'prepend_child'
```

--------------------------------

### Get HTML Heading Level

Source: https://soupault.net/reference-manual

Returns the heading level (1-9) for elements matching <h[1-9]>. Returns zero for non-heading elements or non-elements.

```lua
HTML.get_heading_level(element)
```

--------------------------------

### Insert Warning Before Blink Element

Source: https://soupault.net/reference-manual

This snippet demonstrates how to find a 'blink' element, get its parent, create a warning paragraph, and insert it before the blink element.

```lua
blink_elem = HTML.select_one(page, "blink")
if elem then
  parent = HTML.parent(blink_elem)
  warning = HTML.create_element("p", "Warning: blink element ahead!")
  HTML.insert_before(parent, warning)
end

```

--------------------------------

### Netlify Configuration for Deployment

Source: https://soupault.net/tips-and-tricks/deployment

This TOML configuration file tells Netlify where to publish the built site and which script to run for the build process. The 'publish' directory should match your site's output directory.

```toml
[build]
  publish = "build/"
  command = "./netlify.sh"

```

--------------------------------

### Create SourceHut Link

Source: https://soupault.net/plugins

Use the `<sourcehut>` tag to create a link to a SourceHut project. Specify the project in the format 'owner/repo'. If the project is omitted, the content of the tag is used as the project.

```html
<sourcehut project="dmbaturin/soupault">soupault</sourcehut>

```

```html
<sourcehut>dmbaturin/soupault</sourcehut>

```

--------------------------------

### Include Subsections for Section Targeting

Source: https://soupault.net/reference-manual

Set 'include_subsections = true' to make the 'section' option apply to a directory and all its subdirectories.

```TOML
# If you want a widget to apply to a directory and its subdirectories, add `include_subsections = true`.

```

--------------------------------

### Configure Footnotes Widget

Source: https://soupault.net/blog/limiting-widgets

Example configuration for the footnotes widget. This widget will only be active on pages containing a `<div id="footnotes">` element.

```toml
[widgets.footnotes]
  widget = "footnotes"

  selector = "div#footnotes"

  footnote_selector = ".footnote"
  footnote_link_class = "footnote"
  back_links = true
  link_id_prepend = "footnote-"
  back_link_id_append = "-ref"

```

--------------------------------

### Soupault Configuration for Math Widgets

Source: https://soupault.net/tips-and-tricks/static-rendering

Soupault configuration to use KaTeX for rendering inline and display math. It defines selectors and commands to process math elements.

```toml
[widgets.inline-math]
  widget = "preprocess_element"
  selector = ".inline-math"
  command = "node scripts/katex.js"
  action = "replace_content"

[widgets.display-math]
  widget = "preprocess_element"
  selector = ".display-math"
  command = "DISPLAY=1 node scripts/katex.js"
  action = "replace_content"

```

--------------------------------

### Syntax Highlighting Widget

Source: https://soupault.net/reference-manual

This widget preprocesses elements with a class starting with 'language-' to apply syntax highlighting. It dynamically determines the language from the class name.

```toml
[widgets.highlight]
  widget = "preprocess_element"
  selector = '*[class^="language-"]'
  command = 'highlight -O html -f --syntax=$(echo $ATTR_CLASS | sed -e "s/language-//")'
```

--------------------------------

### Exclude Paths Using Regular Expressions

Source: https://soupault.net/reference-manual

Use 'exclude_path_regex' with Perl-compatible regular expressions to exclude pages matching a pattern. This example excludes all section index pages.

```TOML
[widgets.toc]
  # Don’t add a TOC to any section index page
  exclude_path_regex = '^//(.*)/index\.html$'
  # ...

```

--------------------------------

### Sys.mkdir

Source: https://soupault.net/reference-manual

Creates a directory. If the path is several directories deep, and some are missing, creates them as needed (like `mkdir -p`).

```APIDOC
## Sys.mkdir(path)

### Description
Creates a directory. If the path is several directories deep, and some are missing, creates them as needed (like `mkdir -p`).

### Method
POST (conceptual)

### Endpoint
`/sys/mkdir` (conceptual)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path of the directory to create.

### Request Example
```json
{
  "path": "new_folder/sub_folder"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the directory creation was successful.
```
Tokens:
Raw