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

yard-fence 0.9.0 is a Ruby gem that preprocesses Markdown files to prevent YARD from generating noisy `InvalidLink` warnings caused by braces in code examples or placeholders. The update introduces explicit Rake-driven documentation processing, replacing the previous global `at_exit` post-processing to avoid unintended file modifications during unrelated Rake tasks. The gem creates temporary fenced copies of Markdown files for YARD to read, ensuring generated documentation retains copy-pastable code examples without altering source files.

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