0.12.x

0.12.0

Released:

12.05.2025

New and Improved

This release introduces a new formatter for reStructuredText (rST) files. It can be used via:

  1. The VS Code extension, to format complete documents (ALT+SHIFT+F) or selections of text (CTRL+K CTRL+F)

  2. The ubc format CLI command to format one or more files/folders. Note, currently one must use ubc format --preview to run this command, since the functionality is in Beta.

  3. A ubc format --check CLI command option, to check if file contents would have changed during formatting, but not actually modify the files. If any would change then a non-zero exit code is emitted.

Note, in order to ensure the formatter preserves the original “syntax structure” of the text, a comparison is made, between the original and formatted syntax, before the formatted text is written to file. If there are differences, the formatting will error and the new content will not be written.

On trialling the formatter on known projects, it was found that this comparison could fail when formatting blockquotes, i.e. indented blocks of text, since changes in indenting relative to preceding syntax blocks could change its interpretation. Moreover, these existing blockquote blocks were often an unintended result of mis-indented text, e.g.

* bullet point

   block quote as part of bullet item

 block quote after bullet list

Therefore, a linting rule has also been added warning against bare blockquotes, in favour of using specific directives:

block.bare_blockquote: Bare blockquotes can lead to ambiguous parsing, instead use the pull-quote or epigraph directives.

This rule then encourages the more explicit syntax:

* bullet point

  .. pull-quote:: block quote as part of bullet item

.. pull-quote:: block quote after bullet list