How to...

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 (soupault.conf). Then just run soupault in that directory.

→ How to setup a basic project

Run soupault --init in an empty directory. It will create the following directory structure and files:

.
├── site
│   └── index.html
├── soupault.conf
└── templates
    └── main.html

The site/ directory is where your page content files go. The templates/main.html is 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 the 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 soupault.conf in the current working directory and read it. From there it will take the site_dir and build_dir 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. The --site-dir and --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 matching the 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 build/ directory unchanged.

→ How to create a site section

Just create a subdirectory in site/. Every subdirectory automatically becomes a section, e.g. site/pictures/cats.html becomes 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 site/pictures/index.html.

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 site/about.html turns into build/about/index.html, so that on deployed website it can be accessed as http://example.com/about.

For a new website, the choice between /about/ and /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 option. Use clean_urls = false if you want to disable it.

With clean_urls = false, soupault preserves file names exactly, e.g. site/about.htm becomes build/about.htm, and site/projects/soupault.html becomes build/projects/soupault.html.

→ Building your site from pieces

→ Where the page content goes

When soupault builds your website, it takes the empty page template from templates/main.html, 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 content_selector option in the [settings] section. Suppose you want your page content to go to <div id="content">. Then add that div to templates/main.html, find that option in soupault.conf, 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 exclude_page option.

→ 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, e.g. templates/header.html and templates/footer.html. Suppose your header should be in a <div id="header"> and the footer should be in the <div id="footer">.

First, add div's with those ids to your templates/main.html. Then add this to your soupault.conf:

[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 <script> tag 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 id="title". 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 templates/main.html 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 soupault.conf file:

[preprocessors]
  md = "cmark"

Make sure the program is in your PATH. If it's not, you can specify an absolute path there, like 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.html and 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.