ruby / ruby/rdoc

Heading with file path text generate nested <a> tags and result in broken link

Open
#1,635 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Ruby
Stars
930
Forks
465
Avg merge
3d 10h
Merged PRs (30d)
27

Description

When a heading contains text that matches a documented file path the cross reference system wraps the text in a link inside the header's own anchor link, producing invalid nested tags.

If i have a structure like these two files:

  • lib/pathname.rb:
class Pathname
end
  • maintainers.md:
# Maintainers
#### lib/pathname.rb

Then when generating the docs with rdoc --all lib/pathname.rb maintainers.md it generates the html of maintainers_md.html like this:

<h4 id="libpathnamerb">
  <a href="#libpathnamerb"><a href="lib/pathname_rb.html">lib/pathname.rb</a></a>
</h4>

which in the browser the heading ends up with only the inner tag, so clicking it navigates to the file's supposed doc page (which doesn't exist) instead of anchoring.

I think the correct behaviour is for the header to render as a plain anchor without referencing the actual file, because the purpose of a header is to label the section. I also saw this on the maintainers page on ruby docs that had this problem and clicking on a header like lib/pathname.rb goes into a 404.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue with rdoc --all lib/pathname.rb maintainers.md and inspect the generated maintainers_md.html. Compare the heading output with the expected plain section anchor, ensuring the file-path cross-reference does not create nested links. The reported example uses lib/pathname.rb and maintainers.md; no test file is identified.

Written by the indexing model from the issue text.

Assessment

Tech stack
ruby
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.