DEV Community

Cover image for yard-yaml 0.1.1: safer UTF-8 handling for YAML documentation
Peter H. Boling
Peter H. Boling

Posted on

yard-yaml 0.1.1: safer UTF-8 handling for YAML documentation

#ruby #rubygems #yard #yaml

yard-fence logo

yard-yaml 0.1.1 is available.

yard-yaml is a RubyGem that plugs into YARD and helps Ruby projects document YAML files alongside the rest of their API docs. It can discover .yml, .yaml, and Citation File Format (.cff) files, convert them to HTML pages, and expose inline documentation tags such as @yaml and @yaml_file.

This release is mostly about making the converter more resilient around file encodings, plus keeping the generated project tooling current.

What changed

The main user-facing fix is in Yard::Yaml::Converter.from_file.

In 0.1.1 it now:

  • preserves valid UTF-8 text
  • scrubs malformed UTF-8 safely in non-strict mode
  • rejects binary-ish inputs cleanly instead of raising raw encoding crashes

That matters for documentation pipelines because YAML-like files are often edited by different tools, copied between systems, or generated by automation. A documentation build should fail clearly when the input is not text, and it should handle recoverable encoding issues predictably when strict mode is disabled.

Documentation and CI maintenance

This release also includes generated project maintenance from the current kettle-jem template:

  • refreshed generated project tooling
  • refreshed CI support
  • refreshed documentation support
  • generated CI coverage for rdoc ~> 6.11 and >= 7.0

For contributors working across sibling repositories, 0.1.1 also adds documentation_local.gemfile support under KETTLE_RB_DEV, which makes local documentation development smoother in a multi-repo workspace.

Quick usage

Install the gem:

bundle add yard-yaml
Enter fullscreen mode Exit fullscreen mode

Then enable the YARD plugin in .yardopts:

--plugin yaml
Enter fullscreen mode Exit fullscreen mode

From there, yard-yaml can participate in yard doc generation and convert YAML documents, including .cff files, into documentation output.

The plugin also supports inline docstring tags:

# @yaml
# ---
# title: Example YAML
# description: This is an example YAML block.
# ---
Enter fullscreen mode Exit fullscreen mode

And file references:

# @yaml_file path/to/example.yml
Enter fullscreen mode Exit fullscreen mode

Release links

Thanks to everyone building Ruby documentation tooling and keeping project docs close to the code they describe.

Top comments (0)