From 164545de3686c596b5723c93e9d660ba645d6b36 Mon Sep 17 00:00:00 2001 From: Zachary Scott Date: Thu, 13 May 2021 09:28:46 +0900 Subject: [PATCH] Add explanation for GH links vs RDoc generated links cc #28608 --- guides/source/api_documentation_guidelines.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index 5fbcacbf5f..17f08e02bb 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -30,6 +30,17 @@ Please consult the RDoc documentation for help with the and also take into account these [additional directives](https://ruby.github.io/rdoc/RDoc/Parser/Ruby.html). +Links +----- + +Rails API documentation are not meant to be viewed on GitHub and so links should use the RDoc [`link`](https://ruby.github.io/rdoc/RDoc/Markup.html#class-RDoc::Markup-label-Links) markup relative to the current API. + +This is due to differences between GitHub Markdown and the generated RDoc that is published at [api.rubyonrails.org](https://api.rubyonrails.org) and [edgeapi.rubyonrails.org](https://edgeapi.rubyonrails.org). + +For example, we use `[link:classes/ActiveRecord/Base.html]` to create a link to the `ActiveRecord::Base` class generated by RDoc. + +This is preferred over absolute URLs such as `[https://api.rubyonrails.org/classes/ActiveRecord/Base.html]`, which would take the reader outside their current documentation version (e.g. edgeapi.rubyonrails.org). + Wording -------