Examples
EN

Upgrading to 1.0

This page lists what a site owner can observe when moving from 0.22 to 1.0. A site made by hwaro init whose templates you have not changed builds to the same output; the items below matter when you wrote your own templates, call hwaro from scripts, or rely on one of the behaviours named here.

Check your site

  1. Before upgrading, build with 0.22 into a directory you keep: hwaro build -o /tmp/site-0.22.
  2. Upgrade, then run hwaro doctor. hwaro doctor --fix removes the leftover [plugins] section.
  3. Build with 1.0 and read the warnings: hwaro build -o /tmp/site-1.0.
  4. Compare the two: diff -r /tmp/site-0.22 /tmp/site-1.0. Every difference should be one of the items on this page.

To see only what template escaping changes, follow Coming from 0.x. What later 1.x releases keep working is on the Stability page.

Changes that need action

Templates escape by default

Templates whose output is HTML or XML now escape every printed value unless it is safe, as Jinja2 does. Text your templates printed raw ({{ page.title }} with &, < or a quote in it) is escaped, which is what you want. Author HTML you print as markup now shows as text:

{{ page.extra.banner }}          {# 0.22: markup    1.0: &lt;b&gt;…&lt;/b&gt; #}
{{ page.extra.banner | safe }}   {# markup in both #}

In practice this is most often a translated string or a data value that carries a tag, printed through t:

# i18n/en.toml
lede = "Every request becomes a <b>flow</b>."
<p>{{ "home.lede" | t }}</p>          {# 1.0: the <b> shows as text #}
<p>{{ "home.lede" | t | safe }}</p>   {# markup, in 0.22 and in 1.0 #}

Adding | safe does not change what 0.22 prints, so you can make the change before upgrading.

The values Hwaro renders as HTML (content, page.summary, toc, the *_tags variables, pagination) print as before, and | e on them still escapes them, so {{ p.summary | escape | xml_escape }} in a feed template keeps working. JSON, text and CSV outputs do not change.

To keep the 0.22 behaviour for the whole site:

[templates]
autoescape = false

With that setting a site renders byte for byte as it did in 0.22. See HTML Escaping for the rules and for a way to list every place the default changes on your site.

[plugins] was removed

The section was read and never used, and every config.toml written by an older hwaro init has it. Each command now prints:

Key 'plugins' in config.toml was removed in 1.0 — hwaro does not read it; delete the [plugins] section to silence this warning.

Delete the section, or run hwaro doctor --fix.

Removed commands and flags

Scripts and CI jobs that call these now stop with exit code 2.

0.22 1.0 Use instead
hwaro tool ci github-actions unknown command 'tool ci' hwaro tool platform github-pages (writes the same workflow file)
hwaro tool doctor unknown command 'tool doctor' hwaro doctor (same flags)
hwaro serve --live-reload Invalid option: --live-reload Drop the flag. Live reload is on by default; --no-live-reload turns it off.

Regenerate shell completions with hwaro completion <shell>.

hwaro serve needs a config.toml

Without one it used to warn and serve defaults. It now stops with config.toml not found and exit code 3, as hwaro build does. Run it from the project directory or pass -i DIR.

hwaro serve behind a tunnel or a reverse proxy

The dev server answers only Host names it recognises: loopback addresses, the machine name, the bind address and the host in base_url. Any other name gets 403. Pass --allow-host NAME or set allowed_hosts under [serve] for the name your tunnel or proxy uses. See CLI.

Template tests with an operator after the argument

A test argument written without parentheses is one value, as in Jinja2:

{% if page.url is startswith "/blog" ~ "/" %}    {# now: (page.url is startswith "/blog") ~ "/" — always true #}
{% if page.url is startswith("/blog" ~ "/") %}   {# what was meant #}

The build warns at each such place and prints the parenthesised form to use. Output is not changed for you.

Variables from {% include … without context %}

A {% set %} or {% macro %} at the top level of a partial included without context used to stay visible to the including template, and to later pages built by the same worker, so the same sources could build differently from run to run. It now ends with the partial, as with any other include. A template that read such a variable finds it undefined; share variables and macros with {% import %} or {% from %}.

File names stored in decomposed form (NFD)

Page URLs and output file names are now in composed form (NFC) whatever form the file system stored. Names made by some macOS tools are stored decomposed, which affects Korean and accented names in particular. If such a site was published with decomposed URLs, those URLs no longer exist after a 1.0 build. Add each old spelling to the page's aliases, which are kept exactly as written, or redirect on the server.

include_code and include_md

They refuse files under .git/ and dotenv files (.env and .env.*, except .env.example, .env.sample and .env.template). A page that included one now fails the build.

hwaro tool unused-assets --delete in scripts

Outside an interactive terminal it needs --force; it no longer accepts a piped y.

Dates

A date outside the documented forms (YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, RFC 3339), such as one with a two-digit year or an offset past ±23:59, gets the "not a recognised date" warning and the page is treated as undated. Some of these were read silently before. A written UTC offset is always honoured.

Output changes you may notice

New warnings and errors

Scripts and CI