### 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 = ""
page_file_extensions = ["htm", "html"]
[widgets.set-title]
selector = "h1"
default = "My website"
[widgets.generator-meta]
widget = 'insert_html'
selector = 'head'
html = ''
```
--------------------------------
### 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
Why soupault?
Date:
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 baturin.org 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.
```
--------------------------------
### 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
This is an introductory paragraph. It’s long and only interesting for the really dedicated readers.
Everyone else will just skip it.
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.
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 elements in the page body to