What page formats can soupault work with?

Soupault can work with any page format that can be converted to HTML, because it operates on the HTML element tree rather than on a specific source syntax. Markdown is supported out of the box, and you can configure conversion commands for other file extensions so soupault calls the right external tool automatically when it loads a page. The practical condition is that you have a converter that turns your source format into HTML — once that exists, soupault’s features apply the same way regardless of what you wrote the page in.

Why format flexibility is possible

Most static site generators treat HTML as an output-only format: templates generate it, but the generator itself doesn’t read or manipulate the resulting markup. Soupault instead treats HTML as a first-class format and works on the element tree. That design choice is what lets it accept pages from many source formats — by the time soupault processes a page, it is working with HTML elements, not with Markdown, reStructuredText, or AsciiDoc syntax.

This also means features behave consistently across formats. A table of contents, an include, or a rewrite rule does not need a separate implementation for each source language.

Built-in Markdown support

Markdown works without extra configuration. If you are starting a blog or an online book, soupault provides ready-to-use blueprints, so you don’t have to assemble a Markdown pipeline yourself.

Configuring converters for other formats

For anything beyond Markdown, you map a file extension to a conversion command. Soupault runs that command when it loads a page with that extension. The documented example uses a [preprocessors] section:

[preprocessors]
md = `cmark --unsafe --smart`
rst = `pandoc -f rst -t html`
adoc = `asciidoctor --embedded -o -`

Read this as a pattern rather than a fixed list:

• The key (md, rst, adoc) is the file extension soupault should match.
• The value is the shell command that reads the source and writes HTML.
• Each command is invoked automatically on page load, so you don’t run converters by hand before building.

The same mechanism is what makes the “any format” claim concrete: if a tool can emit HTML, you can wire it in.

What this looks like in practice

Suppose you keep documentation in reStructuredText and notes in AsciiDoc, alongside Markdown blog posts. You add entries for rst and adoc to [preprocessors], point them at pandoc and asciidoctor, and leave md on the built-in path. When soupault loads each page, it converts the source to HTML first, then applies your site-wide rules — menus, includes, rewrites — uniformly. You don’t maintain separate logic per format, and you don’t need client-side JavaScript to compensate for a generator that can’t read your markup.

You can also write HTML pages by hand. Since HTML is the native format, hand-written pages need no conversion step at all.

Choosing a format

The deciding factor is usually what your content already is. Since all features work the same regardless of source format, there is little reason to convert existing material just to fit the generator.

Common sticking points

• The converter must output HTML to stdout in a form soupault can parse. Check the flags your tool needs for that; the example commands show tool-specific options such as --unsafe --smart, -t html, and -o -.
• Extension matching is what triggers conversion. A file whose extension has no entry and isn’t Markdown or HTML won’t be converted the way you expect.
• Conversion happens at load time. If a converter fails or isn’t installed, the page won’t reach the element-tree stage where soupault’s features apply.

If you want to see the workflow end to end, soupault’s own guides cover creating a blog setup from scratch and using it as a post-processor for an existing site.