Skip to content

Commit 12f4e96

Browse files
Add recommendations on link formatting in documentation
1 parent 02cc9d4 commit 12f4e96

File tree

1 file changed

+30
-0
lines changed

1 file changed

+30
-0
lines changed

doc/contributing/documentation_guide.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,36 @@ will be autolinked:
199199
If not, or if you suppress autolinking, consider forcing
200200
[monofont](rdoc-ref:RDoc::MarkupReference@Monofont).
201201
202+
### Explicit Links
203+
204+
When writing an explicit link, follow these guidelines.
205+
206+
#### +rdoc-ref+ Scheme
207+
208+
Use the +rdoc-ref+ scheme for:
209+
210+
- A link in core documentation to other core documentation.
211+
- A link in core documentation to documentation in a standard library package.
212+
- A link in a standard library package to other documentation in that same
213+
standard library package.
214+
215+
See section "+rdoc-ref+ Scheme" in {Links}[rdoc-ref:RDoc::MarkupReference@Links].
216+
217+
#### URL-Based Link
218+
219+
Use a full URL-based link for:
220+
221+
- A link in standard library documentation to documentation in the core.
222+
- A link in standard library documentation to documentation in a different
223+
standard library package.
224+
225+
Doing so ensures that the link will valid even when the package documentation
226+
is built independently (separately from the core documentation).
227+
228+
The link should lead to a target in https://docs.ruby-lang.org/en/master/.
229+
230+
Also use a full URL-based link for a link to an off-site document.
231+
202232
### Variable Names
203233
204234
The name of a variable (as specified in its call-seq) should be marked up as

0 commit comments

Comments
 (0)