Release Notes

4.0.0

16 November 2026

New Features

  • Add Item.resources, which holds all the unhandled files (such as images) in the same folder
  • Fix Swift language mode warning by making metadata: required in register
    The EmptyMetadata.self default makes the compiler infer M from a default value while other parameters also use M. The compiler warns that this will be an error in a future Swift language mode.
  • Remove deprecated code
  • Make Saga.hashed output a warning when giving it a non-existing path

Bugfixes

  • Fix Saga.hashed for localized files
  • Make a slug override on an index.md item replace its folder name
    A slug override on articles/hello-world/index.md (as specified in its frontmatter) put the page at articles/hello-world/<slug>/index.html. It now replaces the folder name instead.

Documentation Changes

  • Add migration docs for Saga 4

BREAKING CHANGES

  • ItemRenderingContext.resources is gone, switch to Item.resources instead.
  • Every register call needs an explicit metadata: argument. Pass EmptyMetadata.self where you relied on the default.
  • Deprecated APIs are removed:
    • ignore(_:): use Saga/ignoreChanges(_:).
    • register(write:): use Saga/afterRead(_:) or Saga/afterWrite(_:).
    • sitemap(baseURL:filter:) with a (Path) -> Bool filter: use Saga/sitemap(baseURL:filter:), whose filter also receives the item, (Path, AnyItem?) -> Bool.
    • atomFeed(…, dateKeyPath:): use Saga/atomFeed(title:author:baseURL:limit:itemTitle:summary:image:date:), which takes a closure or a key path like \.date.
  • With i18n, Saga/hashed(_:) now takes the file’s path in the output folder rather than the input folder. For example /articles/chart.png rather than /en/articles/chart.png, or /nl/artikelen/chart.png rather than /nl/articles/chart.png. Files outside locale folders, like /static/style.css, are unaffected.