DEV Community

Cover image for yard-fence 0.9.0: cleaner YARD docs when Markdown braces get in the way
Peter H. Boling
Peter H. Boling

Posted on

yard-fence 0.9.0: cleaner YARD docs when Markdown braces get in the way

#ruby #rubygems #yard #opensource

yard-fence logo

🤺 yard-fence 0.9.0 is out.

This is the first blog post I have written for the gem, so I will start with the short version:

yard-fence is a Ruby gem that helps YARD generate cleaner documentation from Markdown files that contain braces.

If you have ever had README examples, inline code, or template placeholders like {issuer} or {{TOKEN}} cause noisy YARD InvalidLink warnings, yard-fence exists for that problem.

The problem

YARD is great at generating Ruby API documentation, and it can include Markdown content like a README in the generated docs. The trouble starts when Markdown content contains brace-heavy examples.

That can happen in a lot of normal documentation:

Use `{issuer}` as the issuer placeholder.

```ruby
config.headers = { "Authorization" => "Bearer {{TOKEN}}" }
```
Enter fullscreen mode Exit fullscreen mode

Those braces are ordinary text to the author, but YARD can interpret brace content as reference/link syntax. The result is documentation noise, usually in the form of InvalidLink warnings.

Ignoring those warnings is tempting, but it weakens the signal from the documentation build. Once a build always emits known warnings, new warnings are easier to miss.

What yard-fence does

yard-fence puts a small preprocessing fence around the Markdown files YARD reads.

During the Rake-based YARD workflow, it:

  • Copies top-level Markdown and text files into tmp/yard-fence/
  • Replaces ASCII braces inside fenced code blocks, inline code spans, and simple placeholders with visually similar fullwidth braces
  • Points YARD at the staged files instead of the originals
  • Lets YARD generate HTML without treating those braces as links
  • Restores the generated HTML back to normal ASCII {} braces afterward

The important part: your generated docs still contain copy-pastable code examples.

The conversion is temporary staging for YARD, not a change to your source files.

What changed in 0.9.0

The main 0.9.0 change is that documentation processing is now explicitly Rake-driven.

Projects should define their YARD task, then call:

Yard::Fence.install_rake_tasks!(:yard)
Enter fullscreen mode Exit fullscreen mode

That wires yard:fence:prepare before the selected YARD task and runs HTML post-processing after the YARD task completes.

This release also removes global at_exit post-processing. That is intentional. Raw yard or bin/yard does not run the full yard-fence workflow anymore unless the caller invokes the Rake-integrated documentation task.

The practical fix in 0.9.0: loading YARD during unrelated rake tasks no longer clears or rewrites docs/.

Installation

With Bundler:

bundle add yard-fence
Enter fullscreen mode Exit fullscreen mode

Or install the gem directly:

gem install yard-fence
Enter fullscreen mode Exit fullscreen mode

Basic usage

Use the Rake integration so the prepare and postprocess steps run around the YARD build:

require "yard"
require "yard/fence"

YARD::Rake::YardocTask.new(:yard) { |t| t.files = [] }
Yard::Fence.install_rake_tasks!(:yard)
Enter fullscreen mode Exit fullscreen mode

Then build docs with:

bundle exec rake yard
Enter fullscreen mode Exit fullscreen mode

If your project exposes bin/yard, treat it the same as raw yard: it runs YARD itself, but it does not run the yard-fence Rake integration.

Recommended .yardopts

Point YARD at the staged Markdown/TXT files:

--plugin fence
-e yard/fence/hoist.rb
--readme tmp/yard-fence/README.md
--charset utf-8
--markup markdown
--markup-provider kramdown
--output docs
'lib/**/*.rb'
-
'tmp/yard-fence/*.md'
'tmp/yard-fence/*.txt'
Enter fullscreen mode Exit fullscreen mode

This keeps YARD away from the unsanitized originals during the documentation build.

Environment variables

yard-fence has a few small controls:

Variable Default Description
YARD_FENCE_DISABLE false Disable all yard-fence processing
YARD_FENCE_CLEAN_DOCS false Clear docs/ before regeneration
YARD_DEBUG false Enable debug output

For example, if Markdown files were removed and you want to avoid stale generated pages:

YARD_FENCE_CLEAN_DOCS=true bundle exec rake yard
Enter fullscreen mode Exit fullscreen mode

The tmp/yard-fence/ staging directory is always cleared automatically before regeneration.

Release links

🤺 If your YARD docs have noisy brace-related InvalidLink warnings, give yard-fence a try.

Top comments (0)