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.

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

The 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.

The 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 templates/footer.html file:

[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 deploy effect.

Default template and content selector

The default_template option defines the empty page file where your page contents are inserted. The templates/ 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.

The 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".

Doctype

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.

Clean URLs

Like the HOWTO already says, this option allows you to choose between “clean” and “traditional” URLs, i.e. between site/about.html becoming build/about/index.html or build/about.html. 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

The page_file_extensions options defines which files will be processed as pages, that is, parsed and inserted into the empty page defined by 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.