{"slug": "yard-fence-0-9-0-cleaner-yard-docs-when-markdown-braces-get-in-the-way", "title": "yard-fence 0.9.0: cleaner YARD docs when Markdown braces get in the way", "summary": "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.", "body_md": "🤺 yard-fence\n0.9.0 is out.\nThis is the first blog post I have written for the gem, so I will start with the short version:\nyard-fence\nis a Ruby gem that helps YARD generate cleaner documentation from Markdown files that contain braces.\nIf you have ever had README examples, inline code, or template placeholders like {issuer}\nor {{TOKEN}}\ncause noisy YARD InvalidLink\nwarnings, yard-fence\nexists for that problem.\nYARD 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.\nThat can happen in a lot of normal documentation:\nUse `{issuer}` as the issuer placeholder.\n``` ruby\nconfig.headers = { \"Authorization\" => \"Bearer {{TOKEN}}\" }\n```\nThose 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\nwarnings.\nIgnoring 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.\nyard-fence\nputs a small preprocessing fence around the Markdown files YARD reads.\nDuring the Rake-based YARD workflow, it:\ntmp/yard-fence/\n{}\nbraces afterwardThe important part: your generated docs still contain copy-pastable code examples.\nThe conversion is temporary staging for YARD, not a change to your source files.\nThe main 0.9.0 change is that documentation processing is now explicitly Rake-driven.\nProjects should define their YARD task, then call:\nYard::Fence.install_rake_tasks!(:yard)\nThat wires yard:fence:prepare\nbefore the selected YARD task and runs HTML post-processing after the YARD task completes.\nThis release also removes global at_exit\npost-processing. That is intentional. Raw yard\nor bin/yard\ndoes not run the full yard-fence\nworkflow anymore unless the caller invokes the Rake-integrated documentation task.\nThe practical fix in 0.9.0: loading YARD during unrelated rake tasks no longer clears or rewrites docs/\n.\nWith Bundler:\nbundle add yard-fence\nOr install the gem directly:\ngem install yard-fence\nUse the Rake integration so the prepare and postprocess steps run around the YARD build:\nrequire \"yard\"\nrequire \"yard/fence\"\nYARD::Rake::YardocTask.new(:yard) { |t| t.files = [] }\nYard::Fence.install_rake_tasks!(:yard)\nThen build docs with:\nbundle exec rake yard\nIf your project exposes bin/yard\n, treat it the same as raw yard\n: it runs YARD itself, but it does not run the yard-fence\nRake integration.\nPoint YARD at the staged Markdown/TXT files:\n--plugin fence\n-e yard/fence/hoist.rb\n--readme tmp/yard-fence/README.md\n--charset utf-8\n--markup markdown\n--markup-provider kramdown\n--output docs\n'lib/**/*.rb'\n-\n'tmp/yard-fence/*.md'\n'tmp/yard-fence/*.txt'\nThis keeps YARD away from the unsanitized originals during the documentation build.\nyard-fence\nhas a few small controls:\nFor example, if Markdown files were removed and you want to avoid stale generated pages:\nYARD_FENCE_CLEAN_DOCS=true bundle exec rake yard\nThe tmp/yard-fence/\nstaging directory is always cleared automatically before regeneration.\n🤺 If your YARD docs have noisy brace-related InvalidLink\nwarnings, give yard-fence\na try.", "url": "https://wpnews.pro/news/yard-fence-0-9-0-cleaner-yard-docs-when-markdown-braces-get-in-the-way", "canonical_source": "https://dev.to/galtzo/yard-fence-090-cleaner-yard-docs-when-markdown-braces-get-in-the-way-2683", "published_at": "2026-05-24 06:29:36+00:00", "updated_at": "2026-05-24 06:31:12.901709+00:00", "lang": "en", "topics": ["developer-tools", "open-source"], "entities": ["yard-fence", "YARD", "Ruby"], "alternates": {"html": "https://wpnews.pro/news/yard-fence-0-9-0-cleaner-yard-docs-when-markdown-braces-get-in-the-way", "markdown": "https://wpnews.pro/news/yard-fence-0-9-0-cleaner-yard-docs-when-markdown-braces-get-in-the-way.md", "text": "https://wpnews.pro/news/yard-fence-0-9-0-cleaner-yard-docs-when-markdown-braces-get-in-the-way.txt", "jsonld": "https://wpnews.pro/news/yard-fence-0-9-0-cleaner-yard-docs-when-markdown-braces-get-in-the-way.jsonld"}}