Vendored Rails docs emit broken local links to non-generated markdown pages

[skatkov]

Summary

Generated markdown for vendored Rails docs contains many local links to markdown files that are never emitted.

These are user-visible broken links in the final vendor/docs/rails output.

Reproduction

1. Run rake vendor:setup.
2. Run rake vendor:docs:rails.
3. Open generated files in vendor/docs/rails/.
4. Follow local links that point into source-file-shaped paths such as actionpack/lib/..._rb.md or repository README-shaped paths.

Examples

• vendor/docs/rails/AbstractController/Caching/Fragments.md:30
  • Emits: ../../actionpack/lib/abstract_controller/url_for_rb.md
• vendor/docs/rails/AbstractController/UrlFor.md:5
  • Emits: ../actionpack/lib/abstract_controller/url_for_rb.md
• vendor/docs/rails/ActionCable/Connection/Base.md:105
  • Emits: ../../actionpack/lib/action_dispatch/middleware/request_id_rb.md
• vendor/docs/rails/ActiveJob/EnqueueAfterTransactionCommit/ActiveJobMethods.md:9
  • Emits: ../../activejob/lib/active_job/enqueue_after_transaction_commit_rb.md
• vendor/docs/rails/ActiveJob/QueueAdapters.md:19
  • Emits: ../activejob/README_md.md

None of those targets exist in the generated vendored output tree.

Actual Result

The generated Rails docs contain broken local links to non-existent markdown files.

In a rendered-link audit of the current vendored output, I found 102 broken local links in vendor/docs/rails.

Expected Result

When a reference resolves to a generated page, the link should target that emitted markdown path.

When there is no generated page for the reference, the output should either:

• render plain text, or
• render some other valid non-broken representation.

Notes

This seems related to the older closed path/linking work in #9, but there are still unresolved path mappings in the current vendored Rails output.

[skatkov]

RDoc master comparison note: improved, but not fixed.

Tested full Rails docs with ruby/rdoc master at bc0baee787609f2205e8f1103f3e1d36b923184a.

Counts from the same link audit:

• released RDoc 7.2.0: 185 broken local links in full Rails docs
• RDoc master: 105 broken local links in full Rails docs

Some source-file-shaped examples improve under master, but broken generated local targets remain, including ActiveJob/QueueAdapters.md -> ../activejob/README_md.md plus several bracket/autolink cases tracked by #62.

Related upstream RDoc link behavior:

• rdoc links differ between generated docs and github ruby/rdoc#188
• Invalid link parsing - broken link if ends in '.md' ruby/rdoc#890