Vendored Rails docs emit broken intra-page anchors under GFM

[skatkov]

Summary

Generated markdown for vendored Rails docs contains many intra-page links that point to fragment ids that do not exist in the final GitHub Flavored Markdown output.

This breaks navigation on GitHub and in other GFM renderers even though the markdown is otherwise parseable.

Reproduction

1. Run rake vendor:setup.
2. Run rake vendor:docs:rails.
3. Open the generated files in vendor/docs/rails/.
4. Click the generated section links in GitHub, or inspect them with a GFM renderer such as Commonmarker.

Examples

• vendor/docs/rails/AbstractController/Base.md:4
  • Emits: [Abstract Controller](#class-abstractcontroller-base-abstract-controller-base)
  • The page explicitly defines <a id="class-abstractcontroller-base"></a>, so the emitted fragment does not exist.
• vendor/docs/rails/ActionController/ConditionalGet.md:13
  • Emits: [Options](#method-i-expires_in-options)
  • That fragment is not generated as an anchor in the final page.
• vendor/docs/rails/ActionController/ConditionalGet.md:36
  • Emits: [Examples](#method-i-expires_in-examples)
  • Same problem.
• vendor/docs/rails/ActionController/Streaming.md:12
  • Emits: Streaming.md#module-actioncontroller-streaming-middlewares
  • The section heading at line 116 is rendered as ## [Middlewares](#...), but the referenced fragment is not present.

Actual Result

Generated Rails markdown contains many broken section and heading links.

In a rendered-link audit of the current vendored output, I found 888 missing anchors across vendor/docs/rails.

Expected Result

Any generated intra-page or same-file heading link should point to an anchor that actually exists in the final markdown/GFM output.

Acceptable outcomes would be:

• generate fragment ids that match the emitted markdown headings, or
• stop generating these links when there is no stable target anchor.

Notes

This appears related to the older closed anchor work in #14, but the remaining problem is specifically about section/heading links in vendored rendered output, not just code object anchors.

[skatkov]

RDoc master comparison note: still reproduces, though the total problem is smaller.

Tested with ruby/rdoc master at bc0baee787609f2205e8f1103f3e1d36b923184a. Full Rails docs still contain missing GFM anchors. Examples observed under master:

• AbstractController/Base.md links to #class-abstractcontroller-base-abstract-controller-base, while the emitted explicit anchor is class-abstractcontroller-base.
• ActionController/Streaming.md links to Streaming.md#module-actioncontroller-streaming-middlewares, but that fragment is not present in the final Markdown/GFM anchor set.

Related upstream RDoc issues/docs:

• Heading with file path text generate nested <a> tags and result in broken link ruby/rdoc#1635
• rdoc links differ between generated docs and github ruby/rdoc#188
• https://github.com/ruby/rdoc/blob/master/doc/markup_reference/markdown.md#anchor-links