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

> Source: <https://dev.to/galtzo/yard-fence-090-cleaner-yard-docs-when-markdown-braces-get-in-the-way-2683>
> Published: 2026-05-24 06:29:36+00:00

🤺 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.
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}}" }
```
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.
yard-fence
puts a small preprocessing fence around the Markdown files YARD reads.
During the Rake-based YARD workflow, it:
tmp/yard-fence/
{}
braces afterwardThe 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.
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)
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/
.
With Bundler:
bundle add yard-fence
Or install the gem directly:
gem install yard-fence
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)
Then build docs with:
bundle exec rake yard
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.
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'
This keeps YARD away from the unsanitized originals during the documentation build.
yard-fence
has a few small controls:
For example, if Markdown files were removed and you want to avoid stale generated pages:
YARD_FENCE_CLEAN_DOCS=true bundle exec rake yard
The tmp/yard-fence/
staging directory is always cleared automatically before regeneration.
🤺 If your YARD docs have noisy brace-related InvalidLink
warnings, give yard-fence
a try.