Tweaking the configuration
For simplicity, soupault docs (and these posts) often talk about directories and behaviour
as if they are set in stone, but in fact those are just defaults. In reality, most options
are configurable and you can change them if you want to. Today we'll walk through the options
from the default config generated by
soupault --init and discuss what they do and
why you may want to change them.
site/and generated pages go to
build/. Those are default values for
build_dir. If you are migrating from a hand-cranked workflow or another website generator, changing the directory options to match the setup you already have can save you a bit of time.
Thanks to those defaults, soupault can function without a config file at all. It will show a warning about missing config file, but it will work. The main reason soupault --init creates a default config is to tell you what the defaults are and make it easier to change them. Here is the default config from 1.3.2:
[settings] strict = true verbose = false build_dir = "build" site_dir = "site" default_template = "templates/main.html" content_selector = "body" doctype = "" clean_urls = true page_file_extensions = ["htm", "html", "md", "rst", "adoc"]
Strict and verbose
verbose option makes soupault tell you about everything it's doing. When that option is undefined,
soupault will only print warnings and errors, so successful website build is completely silent. There are two ways
to make it more chatty: use
verbose = true in the config for a permanent option, or run soupault --verbose
for a one time behaviour change.
strict option defines whether soupault will stop on page processing errors or not. Trying to include a file that doesn't exist
is a typical error of this kind. Suppose you want to include a footer from
templates/footer.html in every page, and you add this to the config
but forget to create the
[widgets.footer] widget = "include" # file doesn't exist yet file = "templates/footer.html" selector = "div#footer"
If you have
strict = true in your config, then build will fail with
[ERROR] Could not process page ...: templates/footer.html: No such file or directory.
If you have
strict = false, it will just show a non-existent file warning and produce pages without a footer.
Site and build dirs
As said above, they define where page content files are stores and where generated pages go. You can use either relative or
absolute paths there: for example, if you run soupault right on your web server, you can use
build_dir = "/var/www/mysite"
for instant deploys, or if you have your Neocities site mounted as a WebDAV directory, you can point soupault to it for the same instant
Default template and content selector
default_template option defines the empty page file where your page contents are inserted. The
directory has no special significance, you can as well use
default_template = "empty.html" to store it in the top level
site directory. I just thought most people will want to keep reusable files in one location and that
templates/ is a sensible
name for it.
content_selector option defines where page content is inserted. By default it's inserted in (or appended to) the HTML body.
If you have a designated place for the page content, set it to a CSS selector that identified that element, like
content_selector = "div#content".
Soupault will remove the original
<!DOCTYPE ...> from your pages. This is a limitation of the HTML processing library it uses,
which I may fix in the future. For now, you can't use different doctype for different pages, but you can specify a doctype globally using the
doctype option. It defaults to the HTML5 doctype, which should be good for most newly written pages.
Like the HOWTO already says, this option allows you to choose between “clean” and “traditional”
URLs, i.e. between
If you already have a website using the traditional structure, you should enable it to avoid breaking the links to your existing pages.
Page file extensions
page_file_extensions options defines which files will be processed as pages, that is, parsed and inserted into the empty page
default_template. All other files will be copied to the build directory unchanged, so that you can store your images
and other non-page files together with page in the site directory. This should also make migrating from hand-managed websites easier.
Early soupault versions used to consider everything inside the site directory a page, which is consistent, but it's a foolish kind of consistency that is completely against the principle of least surprise. Placing a GIF picture in the site directory and ending up with lots of garbage inside your HTML would be quite surprising to webmasters, so I went for an explicit list of file types to process and make into pages.
Note that there is no built-in support for Markdown, reStructuredText, or AsciiDoc, so by default your pages in those formats will be treated as plain text. If you want to use those formats, should specify an HTML converter of your choice for them, see the HOWTO.