- Getting started
- Do I need to change my website to start using soupault?
- How to setup a basic project
- Do I need to keep everything in one directory?
- How to add assets (pictures, CSS...)
- How to create a site section
- How to disable clean URLs
- Building your site from pieces
- Where the page content goes
- How to create a page with unique layout
- How to include external files in pages
- How to insert an HTML snippet
- Enhancing your pages
- Extending soupault's capabilities
- Edge cases
This is a simple “how to” page to help new users get started with soupault. For advanced usage such as automatic section indexing, external scripts, and Lua plugins, consult the reference manual.
You may also want to read step by step guides first:
- For using soupault as an HTML processor for existing websites.
→ Getting started
→ Do I need to change my website to start using soupault?
No. With many other website generators, you need to create a theme/template in their own format to start using them. Soupault can work as an HTML processor for existing websites, so it's much easier to give it a try.
Note that soupault never modifies any files in place, it always reads pages from one directory and outputs processed pages to another. It's thus safe to point at handwritten pages.
The simplest way to try it is to initialize a project,
copy your pages to the
site directory and edit the config (
Then just run
soupault in that directory.
→ How to setup a basic project
soupault --init in an empty directory. It will create the following directory structure and files:
. ├── site │ └── index.html ├── soupault.conf └── templates └── main.html
site/ directory is where your page content files go. The
the page template. The
soupault.conf file is the configuration file for soupault, in the TOML format.
If you run
soupault in that directory, it will build your website and place the processed pages in
build/ directory. You can then deploy your website with any tool of your choice, like
neocities push, rsync, or anything else.
→ Do I need to keep everything in one directory?
No. It makes things easier, but it's not required. By default, soupault will look for
in the current working directory and read it. From there it will take the
options. You can use absolute paths for those options.
You can also override the locations of the config file and the source/output directories from the command line. A UNIX example of overriding everything at once:
SOUPAULT_CONFIG="something.conf" soupault --site-dir some-input-dir --build-dir some-other-dir
On Windows, there's no easy way to set an environment variable for a command like that,
but you can make a batch script or just keep the config file in a parent directory and call soupault from there.
--build-dir options work the same on all platforms.
→ How to add assets (pictures, CSS...)
You can just drop files in the
site/ directory together with pages. Files with extensions
page_file_extensions are considered pages and processed, by default that's
["html", "htm", "md", "rst", "adoc"]. All other files are just copied to the
→ How to create a site section
Just create a subdirectory in
site/. Every subdirectory automatically becomes a section,
build/pictures/cats/index.html if clean URLs
are enabled, or
build/pictures/cats.html if they are disabled.
They can be nested as deep as you want, there is no depth limit. However, section index pages is your responsibility,
so if you want
https://example.com/pictures to work, you should also add
Soupault can be configured to generate a list of all pages in a section, but there still must be a section index page, whether you are maintaining a list of pages in the section by hand or using a script to generate it.
→ How to disable clean URLs
Soupault uses “clean URLs” by default. This means a page like
build/about/index.html, so that on deployed website it can be accessed as
For a new website, the choice between
/about.html is purely aesthetic,
but for people who already have a website and want to switch to managing it with soupault, it can be a real
show stopper since it can break all their links. For this reason, soupault has a
clean_urls = false if you want to disable it.
clean_urls = false, soupault preserves file names exactly, e.g.
→ Building your site from pieces
→ Where the page content goes
When soupault builds your website, it takes the empty page template from
reads content from files in
site/ such as
site/about.html, and inserts it in the template.
By default, it will insert the page content into the
<body> element of the page template.
However, you can insert page content into any element using the
Suppose you want your page content to go to
<div id="content">. Then add that div
templates/main.html, find that option in
and set it to
content_selector = "div#content".
→ How to create a page with unique layout
Using a template saves time and allows easily changing the website layout. However, what if you want to make a page with a unique layout different from the template?
Soupault decides whether to use a template or not by checking if a page file has an
<html> element in it.
It it does not have it, then the file is considered a page body and inserted in the template. If it does, then it's considered
a complete page and only processed by widgets/plugins.
So, to make a unique page, just make it a complete HTML document.
You may also want to exclude it from some widgets using the
→ How to include external files in pages
Suppose all your pages have the same header and footer, and you want to keep them in separate files,
templates/footer.html. Suppose your header should be in a
<div id="header"> and the footer should be in the
div's with those ids to your
Then add this to your
[widgets.header] widget = "include" selector = "div#header" file = "templates/header.html" [widgets.footer] widget = "include" selector = "div#footer" file = "templates/footer.html"
→ How to insert an HTML snippet
Sometimes you just need a small snippet that makes no sense to keep in a separate file.
Suppose you want to add an analytics script to your pages, just one
in the head. You can do it like this:
[widgets.analytics-script] widget = "insert_html" selector = "head" html = '<script src="/scripts/evil-analytics.js"> </script>'
→ Enhancing your pages
→ How to automatically set page title
A website where every page has the same
<title> is a sad sight.
Soupault can set the page title from an element of your choice. This is the config
for this page, that takes the title from an element with
In this page it's a
h1, but it could be anything.
[widgets.page-title] widget = "title" selector = "#title" default = "soupault" append = " — soupault"
→ How to add a table of contents
Soupault can automatically generate tables of contents from heading tags. This is the config for this very page:
[widgets.table-of-contents] widget = "toc" selector = "#generated-toc" min_level = 2 toc_list_class = "toc" toc_class_levels = false numbered_list = true heading_links = true heading_link_text = "→ " heading_link_class = "here" use_heading_slug = true
Remember to add a
<div id="generated-toc"> to
if you want a ToC in every page, or just to pages where you want it.
→ How to add footnotes
If you like footnotes, you can add them to your pages easily. This is the config for this website:
[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"
It assumes that there's a
<div id="footnotes"> in the page.
If you forget to include it in the page, footnotes will not appear.
It considers elements with
class="footnote" footnotes and moves them
to that div. The
back_links option creates links back from footnotes
to their original location, you can set it to
false if you don't like
those links back.
→ Extending soupault's capabilities
→ How to use Markdown and other formats
Unlike many other static website generators, soupault treats HTML as a first-class citizen. In fact, it's the only format it treats that way, there's no built-in support for any other format. If you are switching from another generator like Jekyll, or simply want to use Markdown for some pages that don't need advanced markup, it can be quite limiting though.
The good news is that you can write pages in any format as long as you have a program that converts it to HTML. You just need to specify a preprocessor program for a file extension, and soupault will call it automatically.
For Markdown, I suggest the cmark program.
On GNU/Linux you can install it from repositories and on macOS you can get it from
homebrew. I couldn't find a prebuild version
for Windows though, so I made one (v.0.29.0): cmark.exe.
To use it, just add this to your
[preprocessors] md = "cmark"
Make sure the program is in your
PATH. If it's not, you can specify an absolute path there,
md = '/opt/cmark/bin/cmark' or
md = 'C:\cmark\cmark.exe'.
You can specify preprocessors for as many extensions as you want, so you can easily use multiple formats at once.
→ Edge cases
→ What happens if you have a directory and a page with the same name
Don't do it. It's undefined behaviour and anything may happen.
In the current versions, if you have clean URLs enabled and there are both
site/test/index.html, then the latter will be used. But it just happens to be this way
and may change any time, so don't count on it.