🤺 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.
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: 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.