Soupault 5.3.0 release

Estimated reading time: 6 minutes.

Date: 2026-04-21

Soupault 5.3.0 is available for download from my own server and from GitHub releases. It adds smart punctuation for Markdown and a few more ways to control Markdown rendering, an option to specify the base URL for autogenerated links, an option to exclude certain pages from clean URLs, and a few more bug fixes and improvements. Also, soupault now has official prebuilt binaries for ARM64 macOS.

Platform support

Soupault now offers official prebuilt binaries for macOS on ARM64.

New features

Smart punctuation for Markdown

I realized that the built-in Markdown renderer that soupault uses (Cmarkit) doesn’t support “smart punctuation” (sometimes called smartypants after a popular early implementation). The reason I didn’t notice is that I’m used to just writing HTML entities like “ or entering Unicode characters directly, but it’s still a missing feature that many SSGs offer, so I went on to add it.

Cmarkit does offer a way to extend the renderer, so it was easy to add: I only had to redefine the handler of text nodes.

If it was already there, I might have just added an option to enable it. But since it wasn’t, that made me stop and think how I wanted to be implemented. All software I’d seen so far only offers an option to enable to disable it. I always found it a bit too inflexible.

For example, I think that a dedicated character for ellipsis (“…”) is a good idea, conceptually, but I find that in many fonts it’s far to narrow, so I may not always want every ... replaced with it.

Another point of controversy is the apostrophe character. I like the version that looks like a proper typographic quote (’) but some people may like the straight version and want it to look different from quotes (').

I believe all people should be free to choose, so I made something that could be described as “SmartyPants Ultimate 2026”.

If you set settings.markdown_smart_punctuation = true, all types of “smart punctuation” are enabled by default, but you can disable individual types if you want:

[settings]
    markdown_smart_punctuation = true

    # You can disable individual punctuation substitutions
    # if you only want some of them but not all

    # Replace `` and '' with &ldquo; and &rdquo;
    markdown_smart_quotes = true

    # Replace ' with &rsquo;
    markdown_smart_apostrophe = true

    # Replace --- and -- with &mdash; and &ndash;
    markdown_smart_dashes = true

    # Replace "..." with &hellip;
    markdown_smart_ellipsis = true

An option to render math delimiters in Markdown as HTML

By default, soupault’s Markdown processor renders math delimiters as \[ \] and \( \) for the client-side JavaScript version of KaTeX.

That is not very conductive to build-time rendering because it doesn’t give you HTML selectors to point your KaTeX rendering widget at.

Now there is an option to render math delimiters as HTML instead.

If you set settings.markdown_math_delimiters_html = true, soupault will render them as <span class="math-inline">, <span class="math-display"> and <div class="math-display"> to facilitate their manipulation with widgets.

Thanks to Geert Mulders for the patch!

An option to disable Markdown extensions

It’s now possible to disable Markdown extensions (strike-through with ~~, tables, etc.) and limit the Markdown flavor to strict CommonMark.

[settings]
    markdown_strict_commonmark = false

Page data in the index template environment

The following variables related to the current page (i.e., the page where the index is being rendered) are now available in the environment of index_template in index views:

page_file (string) — the source file of the page.
target_dir (string) — the target directory for the page file.
target_file (string) — the full target page output file path.
url (string) — the generated page URL.
nav_path (string list) — the navigation path.

That can be used to customize the template logic and render the index differently on different pages. For example, if you want to avoid a hyperlink to the page itself, you can do something like this:

{% for e in entries %}
{%   if e.url == url %}
  {{e.title}}
{%   else %}
  <a href="{{url}}">{{e.title}}</a>
{%   endif %}
{% endfor %}

Excluding certain pages from clean URLs

Some hosting providers require specific names for certain pages, such as 404.html for the page to be served as an error page properly.

Now there is an option that allows the user to exclude certain page name patterns from clean URLs, whether for technical or aesthetic reasons:

[settings]
  clean_urls_exclude_regexes = ['\d+\.html']

Site URL option

There’s now an option to specify the base URL for links in automatically generated indices.

[settings]
  site_url = "https://example.com"

The absolute_links widget will now use this option as the default base URL if you do not specify the prefix option explicitly.

New Lua plugin functions

Date.format_timestamp(num, format) — formats a Unix timestamp according to format.
String.render_markdown(str) — converts Markdown source to HTML source (that you can parse with HTML.parse() if need be). Smart punctuation and Markdown extension settings are taken from the config.
String.render_markdown(str) — renders a Markdown string into HTML (uses smart punctuation settings defined in the config).

Bug fixes

site_dir that goes more than a single subdirectory deep works correctly again (report by Jay).
Datetime functions in the Lua API correctly raise plugin errors on incorrect arguments.
Fixed a typo in the autogenerated default config (GitHub#90, fix by Will Badart).
The startup hook now has global_data table in its environment automatically and the hook code doesn’t have to define it explicitly before use.

Misc improvements

There are now spell check suggestions for incorrect widget names.
There are now log messages to inform the user where a plugin is loaded from (inline source or file path).