Broken links (404) to Markdown or text documents
If you encounter a broken link (404) error when visiting a Markdown or extra document in library documentation, please check the following before reporting an error:
-
If the file is a Markdown, text file, RDoc file, or other plain text documentation, please verify that the URL in your address bar includes
/file/before the filename. If it does not, this means that the URL was generated incorrectly for documentation hosting by the library. See below for how to correctly report this error to the library author (and not to Rubydoc.info). -
If the file is a Ruby source file, see below on how to report this broken link to the library author.
-
If the file is an image or other binary file, please verify that the URL in your address bar includes
/assets/. If it does not, this means that the image was not correctly configured to be hosted by YARD and rubydoc.info. See below for how to correctly report this error to the library author (and not to Rubydoc.info). -
If the link is meant to go to a class, module, or method, please report this error as a support issue on our support site.
Why Are Links Broken?
YARD, and by extension, rubydoc.info, do not support arbitrary
relative links from Markdown or RDoc documents to other documents.
The reason for this is that the path structure of documents hosted
by rubydoc.info may change from the organizational structure in the
original source tree. For example, when a README.md
file links to an installation.md as a relative link,
it assumes that the files live in the same path. In YARD, documents
are moved under a /file/ path to separate
classes/modules from extra files, which means these documents are
no longer living in the same directory. Similarly, source files are
not hosted by rubydoc.info, so any relative links to a Ruby file
will not work correctly. All links intended to bring a user to a
specific page outside of Rubydoc.info should be absolute URLs to
avoid 404s.
How to Report Broken Links to Library Authors
It is recommended to let library authors know if they have broken links in their documentation. To do this, please report these broken links to the respective library's issue tracker. For RubyGems, you can find the issue tracker site in the links section of the gem's landing page on RubyGems.org. For documentation hosted by GitHub, the GitHub page should provide more information.
When reporting a broken link, please make sure to identify the page and section where the broken link is, both on Rubydoc.info, and in the library's source (raw text files). It is also helpful to remind the authors that rubydoc.info does not support relative path linking to documents, since documents hosted outside of GitHub may be organized differently on disk. Also note that rubydoc.info does not host Ruby source files from a source tree; these files are removed after processing documentation.
To resolve these issues, authors should be providing a full
absolute URL to their documentation, or making use of the
{file:path/to/document} file linking syntax in
YARD. Similarly, if the author wishes to link to a Ruby source
file directly, they must provide an absolute URL to the file in
their source repository (GitHub, etc).