How to use the command 'soupault' (with examples)

The command ‘soupault’ is a static website generator based on HTML element tree rewriting. It can be used to initialize and build static websites, as well as extract metadata from HTML files. This article will provide examples of different use cases of the ‘soupault’ command.

Use case 1: Initialize a minimal website project in the current working directory

Code:

soupault --init

Motivation: The ‘soupault –init’ command is used to initialize a minimal website project in the current working directory. This is useful when starting a new static website project and provides a basic directory structure and configuration file to get started quickly.

Explanation: The ‘–init’ flag is used to indicate the initialization mode. When this flag is passed to the ‘soupault’ command, it creates a basic website project structure in the current working directory. This includes the ‘soupault.toml’ configuration file and some sample content files and directories.

Example output:

Initializing new Soupault website in the current directory...
Website structure created successfully.

Use case 2: Build a website

Code:

soupault

Motivation: The ‘soupault’ command without any arguments is used to build a website. This command executes the configured rules in the ‘soupault.toml’ configuration file and generates the static content for the website. This is useful when you have made changes to the website’s source files and want to update the generated static content.

Explanation: When the ‘soupault’ command is run without any arguments, it reads the configuration from the ‘soupault.toml’ file in the current working directory and applies the configured rules to the website’s source files. It then generates the static content based on these rules and outputs it to the configured output directory.

Example output:

Building website...
Applied 5 rules.
Generated 10 pages.
Website built successfully.

Use case 3: Override default config file and directory locations

Code:

soupault --config config_path --site-dir input_dir --build-dir output_dir

Motivation: The ‘soupault’ command allows you to override the default configuration file and directory locations. This is useful when you want to use a different configuration file or store your website’s source files and generated output in custom directories.

Explanation: The ‘–config’ flag is used to specify the path to a custom configuration file. The ‘–site-dir’ flag is used to specify the input directory where the website’s source files are located. The ‘–build-dir’ flag is used to specify the output directory where the generated static content will be stored.

Example output:

Building website from custom configuration and directories...
Applied 7 rules.
Generated 15 pages.
Website built successfully using custom configuration and directories.

Use case 4: Extract metadata into a JSON file without generating pages

Code:

soupault --index-only --dump-index-json path/to/file.json

Motivation: The ‘soupault’ command can extract metadata from HTML files and dump it into a JSON file without generating the actual web pages. This is useful when you need to extract specific information from the website’s source files, such as title, description, or other custom metadata.

Explanation: The ‘–index-only’ flag is used to indicate that only the metadata needs to be extracted and no web pages should be generated. The ‘–dump-index-json’ flag is used to specify the path to the JSON file where the extracted metadata will be dumped. This JSON file will contain an array of objects, with each object representing the metadata of a single HTML file.

Example output:

[
  {
    "title": "Blog Post 1",
    "date": "2022-01-01",
    "tags": ["technology", "web development"],
    "description": "This is the first blog post."
  },
  {
    "title": "Blog Post 2",
    "date": "2022-01-05",
    "tags": ["programming", "software"],
    "description": "This is the second blog post."
  },
  ...
]

Use case 5: Show the effective config (values from soupault.toml plus defaults)

Code:

soupault --show-effective-config

Motivation: The ‘soupault’ command provides a way to view the effective configuration that will be used for building the website. This is useful when you want to verify the configuration values or check what defaults are being applied.

Explanation: The ‘–show-effective-config’ flag is used to display the effective configuration. This includes the values defined in the ‘soupault.toml’ file merged with any default values. It provides an overview of the applied configuration which can be useful for troubleshooting or understanding how the website will be generated.

Example output:

Effective configuration:

[rule_set]
input_glob = "*.html"
[rule_set.modify_urls]
configurable = true
base_url = "https://example.com/"
[rule_set.copy_resource]
glob = "*.{png,jpg}"
...

Conclusion:

The ‘soupault’ command is a versatile tool for building static websites, processing HTML files, and extracting metadata. With its various flags and options, it offers flexibility and customization for different use cases. Whether you want to initialize a new website project, build a website, extract metadata, or override default configurations, ‘soupault’ has got you covered.