Release Notes
This section provides release notes about recent versions of Verso. When updating to a new version, please read the corresponding release notes. They may contain advice that will help you understand the differences with the previous version and upgrade your projects.
Verso versioning follows Lean's. This means that we release a new version for each Lean release, usually once per month. In particular, note that Verso doesn't follow the semantic versioning model.
Verso 4.31.0 (unreleased)
-
Refactored the build's error reporting into a logging abstraction with severities and structured source locations, improving the consistency of Verso's internal APIs and external error reports. While this was primarily an internal change, there is a breaking change to the signature of
Verso.Genre.Manual.ExtraStep. -
Improve role resolution diagnostics with suggestions and actionable registration errors (#763).
-
Register legacy inline APIs as roles for compatibility (
today,date,sectionRef,index,see,seeAlso) (#763). -
Preserve
#doc/#docssource ranges for LSP document symbols and folding ranges (#771).
Logging Abstraction
The build pipeline previously threaded a bare String → IO Unit error callback through traversal and output generation, and several monads carried their own ad-hoc error loggers.
There was no way to emit a warning.
This release introduces Verso.MonadBuildLog, a uniform logging interface shared across the genres.
A message carries a Verso.Severity (either Verso.Severity.error or Verso.Severity.warning) and an optional source location.
Breaking Change: ExtraStep
Verso.Genre.Manual.ExtraStep no longer takes a String → IO Unit error callback.
Instead, it runs in a monad that has an instance of Verso.MonadBuildLog, so a step can emit both errors and warnings with Verso.reportError and Verso.reportWarning.
Verso 4.30.0 (unreleased)
-
Add support for custom prioritization of search results (#844)
-
Add full-page search interface (#847). There is a small breaking change for custom domains with custom result formatting.
-
Add support for diagrams (#856)
Search Result Prioritization
This release gives authors the ability to affect search result ordering by assigning custom priorities. Priorities may be assigned as follows:
-
Semantic vs full-text results can be assigned overall priority levels.
-
Semantic domains may be weighted, e.g. to boost all technical terms.
-
Within a domain, items may be prioritized, e.g. to lower the priority of release notes relative to other text. This is done in JavaScript in the domain mapper.
-
A genre may weight full-text results for parts based on part metadata.
In the Manual genre, sections can be assigned search priority values using the metadata field Manual.PartMetadata.searchPriority, which affects their full-text and semantic results, both for themselves and their children.
Full-Page Search Interface
Pressing "Enter" in the search box now leads to a full-page search interface that shows more results with more context and includes checkboxes to filter the results by their semantic domain.
As a result, domains with custom search CSS should replace the #search-wrapper selector with the .verso-search-results class.
Verso 4.29.0 (unreleased)
-
Fix Verso folding ranges / TOC for Lean.Doc syntax and #doc (#768)
-
Align Blog inline Lean role naming with Manual; add
{lean}and deprecate{leanInline}(#762) -
A zero-config literate programming feature was added in #809.
Literate Programming
PR #809 added support for a simple literate programming system, in which module docstrings are rendered as the text of a page. While no configuration is necessary to use it, aside from adding Verso as a dependency, some configuration is possible in order to customize aspects of the display. See its section in this guide for more details.
Verso 4.28.0
-
Add Release Notes / Changelog to Verso Users guide (@david-christiansen, @ejgallego, #708)
-
Fix infoview display for inline lean code (@david-christiansen, @ejgallego, #700)