Encyclopedia

Ruby Document format

Markup language

Wikipedia contributorsAdapted for Fathomly · View authors

2 min read
Source updated October 3, 2025

RD (Ruby Document) is a lightweight markup language for writing Ruby-related documents. It can be embedded in Ruby source code.

RD is a traditional format. In modern Ruby, developers tend to write documents in RDoc instead of RD.

01Use

Originally, most documentation in the Ruby world, including for Ruby itself, had been written in RD. Then in 2002, much of it was converted to RDoc format. Although, the Japanese version of the Ruby Reference Manual still remains in RD format.

RD is designed to be written by hand and easily read in its raw form. Most end-users however experience it after it has been converted into HTML or man pages.

RD can be embedded in Ruby code, and pure RD files usually have the extension .rd.

02Sample RD document

This document is syntactically correct RD, which attempts to follow the major conventions on section naming as well.

Source	HTML result
=begin = NAME RD sample - A sample RD document = SYNOPSIS here.is_a?(Piece::Of::Code) print <<"END" This indented block will not be scanned for formatting codes or directives, and spacing will be preserved. END = DESCRIPTION Here's some normal text. It includes text that is ((emphasized)), ((%keyboard%)), (({code}))-formatted, ((\|variable part\|)), ((:indexed:)), and (('as-is'))((-footnote-)). == An Example List This is a bulleted list. Here's another item. * Nested list item. == An ordered List (1) This is the first item (2) second * Nested unordered list. (3) third (1) Nested ordered list (2) its second item =end =begin html <img src="Example.png" align="right" alt="Figure 1." /> <p> Here's some embedded HTML. In this block I can include images, apply <span style="color: green"> styles</span>, or do anything else I can do with HTML. RD processors that aren't outputting HTML will completely ignore it. </p> =end =begin = COPYRIGHT Copyright 2005 J. Random Hacker <jrh@cpan.org>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. =end	NAME RD sample - A sample RD document SYNOPSIS here.is_a?(Piece::Of::Code) print <<"END" This indented block will not be scanned for formatting codes or directives, and spacing will be preserved. END DESCRIPTION Here's some normal text. It includes text that is emphasized, keyboard, code-formatted, variable part, indexed, and as-is^*1. An Example List This is a bulleted list. Here's another item. Nested list item. An ordered List This is the first item second Nested unordered list. start=3 third Nested ordered list its second item Here's some embedded HTML. In this block I can include images, apply styles, or do anything else I can do with HTML. RD processors that aren't outputting HTML will completely ignore it. COPYRIGHT Copyright 2005 J. Random Hacker <jrh@cpan.org>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.

Source

HTML result

=begin = NAME RD sample - A sample RD document = SYNOPSIS here.is_a?(Piece::Of::Code) print <<"END" This indented block will not be scanned for formatting codes or directives, and spacing will be preserved. END = DESCRIPTION Here's some normal text. It includes text that is ((*emphasized*)), ((%keyboard%)), (({code}))-formatted, ((|variable part|)), ((:indexed:)), and (('as-is'))((-footnote-)). == An Example List

This is a bulleted list.
Here's another item.

* Nested list item. == An ordered List (1) This is the first item (2) second * Nested unordered list. (3) third (1) Nested ordered list (2) its second item =end =begin html <img src="Example.png" align="right" alt="Figure 1." /> <p> Here's some embedded HTML. In this block I can include images, apply <span style="color: green"> styles</span>, or do anything else I can do with HTML. RD processors that aren't outputting HTML will completely ignore it. </p> =end =begin = COPYRIGHT Copyright 2005 J. Random Hacker <jrh@cpan.org>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. =end

NAME

RD sample - A sample RD document

SYNOPSIS

here.is_a?(Piece::Of::Code) print <<"END" This indented block will not be scanned for formatting codes or directives, and spacing will be preserved. END

DESCRIPTION

Here's some normal text. It includes text that is emphasized, keyboard, code-formatted, variable part, indexed, and as-is^*1.

An Example List

This is a bulleted list.
Here's another item.
- Nested list item.

An ordered List

This is the first item
second

Nested unordered list.

start=3
third

Nested ordered list
its second item

Here's some embedded HTML. In this block I can include images, apply styles, or do anything else I can do with HTML. RD processors that aren't outputting HTML will completely ignore it.

COPYRIGHT

Copyright 2005 J. Random Hacker <jrh@cpan.org>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.

Watch videos about Ruby Document formatExplainers and documentaries on YouTube (opens in a new tab)

Sources and credits

This article is adapted from the Wikipedia article “Ruby Document format”, written by its contributors and licensed under CC BY-SA 4.0. Fathomly has changed the layout, removed citation markers, navigation and maintenance notices, and adjusted punctuation. This adapted version is shared under the same license. For references, see the original article.

Fathomly is not affiliated with or endorsed by the Wikimedia Foundation. Spotted a problem? Tell us.