RDoc Markup Reference

This document is the comprehensive reference for RDoc’s rdoc markup format. It covers all markup syntax, directives, and formatting options available.

For Ruby-specific features that require actual code (like cross-reference targets and directives that only work in Ruby comments), see RDoc::Example.

RDoc generates GitHub-style anchors for headings. The anchor is the heading text converted to lowercase with spaces replaced by hyphens and special characters removed.

You can link to headings using Markdown-style syntax:

About the Examples

Markup Sources

The sources of markup documentation vary according to the file type:

Note that all of the above applies to RDoc markup-formatted documentation:

Blocks

It’s convenient to think of an RDoc document as a sequence of blocks of various types:

About the blocks:

Paragraphs

A paragraph consists of one or more non-empty lines of ordinary text, each beginning at the current margin.

Note: Here, ordinary text means text that is not identified by indentation, or by unusual initial or embedded characters. See below.

Paragraphs are separated by one or more empty lines.

Example input:

RDoc produces HTML and command-line documentation for Ruby projects.
RDoc includes the rdoc and ri tools for generating and displaying
documentation from the command-line.

You'll love it.

Rendered HTML:

RDoc produces HTML and command-line documentation for Ruby projects. RDoc includes the rdoc and ri tools for generating and displaying documentation from the command-line.

You’ll love it.

A paragraph may contain nested blocks, including:

Verbatim Text Blocks

Text indented farther than the current margin becomes a verbatim text block (or a code block, described next). In the rendered HTML, such text:

The verbatim text block ends at the first line beginning at the current margin.

Example input:

This is not verbatim text.

  This is verbatim text.
    Whitespace is honored.     # See?
      Whitespace is honored.     # See?

  This is still the same verbatim text block.

This is not verbatim text.

Rendered HTML:

This is not verbatim text.

This is verbatim text.
  Whitespace is honored.     # See?
    Whitespace is honored.     # See?

This is still the same verbatim text block.

This is not verbatim text.

A verbatim text block may not contain nested blocks of any kind – it’s verbatim.

Code Blocks

A special case of verbatim text is the code block, which is merely verbatim text that RDoc recognizes as Ruby code:

In the rendered HTML, the code block:

Example input:

Consider this method:

  def foo(name = '', value = 0)
    @name = name      # Whitespace is still honored.
    @value = value
  end

Rendered HTML:

Consider this method:

def foo(name = '', value = 0)
  @name = name      # Whitespace is still honored.
  @value = value
end

Pro tip: If your indented Ruby code does not get highlighted, it may contain a syntax error.

A code block may not contain nested blocks of any kind – it’s verbatim.

Block Quotes

You can use the characters >>> (unindented), followed by indented text, to treat the text as a block quote:

Example input:

Here's a block quote:
>>>
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
  commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
  Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.

  Aenean congue ligula eu ligula molestie, eu pellentesque purus
  faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
  diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
  purus magna ut tortor.

Rendered HTML:

Here’s a block quote:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer commodo quam iaculis massa posuere, dictum fringilla justo pulvinar. Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.

Aenean congue ligula eu ligula molestie, eu pellentesque purus faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum, diam in pellentesque aliquet, mi tellus placerat sapien, id euismod purus magna ut tortor.

Note that, unlike verbatim text, single newlines are not honored, but that a double newline begins a new paragraph in the block quote.

A block quote may contain nested blocks, including:

Lists

Each type of list item is marked by a special beginning:

A list begins with a list item and continues, even across blank lines, as long as list items of the same type are found at the same indentation level.

A new list resets the current margin inward. Additional lines of text aligned at that margin are part of the continuing list item.

A list item may be continued on additional lines that are aligned with the first line. See examples below.

A list item may contain nested blocks, including:

Bullet Lists

A bullet list item begins with a hyphen or asterisk.

Example input:

- An item.
- Another.
- An item spanning
  multiple lines.

* Yet another.
- Last one.

Rendered HTML:

Numbered Lists

A numbered list item begins with digits and a period.

The items are automatically re-numbered.

Example input:

100. An item.
10. Another.
1. An item spanning
   multiple lines.

1. Yet another.
1000. Last one.

Rendered HTML:

  1. An item.

  2. Another.

  3. An item spanning multiple lines.

  4. Yet another.

  5. Last one.

Lettered Lists

A lettered list item begins with letters and a period.

The items are automatically “re-lettered.”

Example input:

z. An item.
y. Another.
x. An item spanning
   multiple lines.

x. Yet another.
a. Last one.

Rendered HTML:

  1. An item.

  2. Another.

  3. An item spanning multiple lines.

  4. Yet another.

  5. Last one.

Labeled Lists

A labeled list item begins with one of:

Example input:

[foo] An item.
bat:: Another.
[bag] An item spanning
      multiple lines.

[bar baz] Yet another.
bam:: Last one.

Rendered HTML:

foo

An item.

bat

Another.

bag

An item spanning multiple lines.

bar baz

Yet another.

bam

Last one.

Headings

A heading begins with up to six equal-signs, followed by heading text. Whitespace between those and the heading text is optional.

You should not use headings beyond level 3, as it becomes difficult for the reader to track the multiple layers of nesting.

Examples:

= Section 1
== Section 1.1
=== Section 1.1.1
=== Section 1.1.2
== Section 1.2
= Section 2
============Still a Heading (Level 6)
\== Not a Heading

A heading may contain only one type of nested block:

Heading Examples

Heading level 1

Above is a level one heading.

Heading level 2

Above is a level two heading.

Heading level 3

Above is a level three heading.

Heading level 4

Above is a level four heading.

Heading level 5

Above is a level five heading.

Heading level 6

Above is a level six heading.

Horizontal Rules

A horizontal rule consists of a line with three or more hyphens and nothing more.

Example input:

---
--- Not a horizontal rule.

-- Also not a horizontal rule.
---

Rendered HTML:

— Not a horizontal rule.

– Also not a horizontal rule.

Directives

Directives for Allowing or Suppressing Documentation

:stopdoc:

:startdoc:

:enddoc:

:nodoc:

For a method definition in C code, the directive must be in the comment line immediately preceding the definition:

/* :nodoc: */
static VALUE
some_method(VALUE self)
{
  return self;
}

Note that this directive has no effect at all when placed at the method declaration:

/* :nodoc: */
rb_define_method(cMyClass, "do_something", something_func, 0);

The above comment is just a comment and has nothing to do with RDoc. Therefore, do_something method will be reported as “undocumented” unless that method or function is documented elsewhere.

For a constant definition in C code, this directive cannot work because there is no “implementation” place for a constant.

With argument all (:nodoc: all), specifies that the class or module should not be documented. By default, however, a nested class or module will be documented.

:doc:

:notnew:

Aliased as :not_new: and :not-new:.

For Ruby code, but not for other RDoc sources, there is a shorthand for :stopdoc: and :startdoc::

# Documented.
#--
# Not documented.
#++
# Documented.

For C code, any of directives :startdoc:, :stopdoc:, and :enddoc: may appear in a stand-alone comment:

/* :startdoc: */
/* :stopdoc: */
/* :enddoc: */

Directive for Specifying RDoc Source Format

:markup:

Directives for Method Documentation

:call-seq:

Note that RDoc can build the calling sequence for a Ruby-coded method, but not for other languages. You may want to override that by explicitly giving a :call-seq: directive if you want to include:

For C code, the directive may appear in a stand-alone comment.

:args:

Aliased as :arg:.

:yields:

Aliased as :yield:.

Directives for Organizing Documentation

By default, RDoc groups:

You can use directives to modify those behaviors.

:section:

The comment block containing this directive:

Example:

# ----------------------------------------
# :section: My Section
# This is the section that I wrote.
# See it glisten in the noon-day sun.
# ----------------------------------------

##
# Comment for some_method
def some_method
  # ...
end

You can use directive :category: to temporarily override the current section.

:category:

Directive for Including a File

:include:

The file content is shifted to have the same indentation as the colon at the start of the directive.

The file is searched for in the directory containing the current file, and then in each of the directories given with the --include command-line option.

For C code, the directive may appear in a stand-alone comment.

Text Markup

Text markup is metatext that affects HTML rendering:

Typeface Markup

Typeface markup can specify that text is to be rendered as italic, bold, monofont, or strikethrough.

Typeface markup may contain only one type of nested block:

Italic

Text may be marked as italic via HTML tag <i> or <em>.

Example input:

<i>Italicized words</i> in a paragraph.

<i>Italicized passage containing *bold* and +monofont+.</i>

Rendered HTML:

Italicized words in a paragraph.

Italicized passage containing bold and monofont.

A single word may be italicized via a shorthand: prefixed and suffixed underscores.

Example input:

_Italic_ in a paragraph.

Rendered HTML:

Italic in a paragraph.

Bold

Text may be marked as bold via HTML tag <b>.

Example input:

<b>Bold words</b> in a paragraph.

<b>Bold passage containing _italics_ and +monofont+.</b>

Rendered HTML:

Bold words in a paragraph.

Bold passage containing italics and monofont.

A single word may be made bold via a shorthand: prefixed and suffixed asterisks.

Example input:

*Bold* in a paragraph.

Rendered HTML:

Bold in a paragraph.

Monofont

Text may be marked as monofont – sometimes called ‘typewriter font’ – via HTML tag <tt> or <code>.

Example input:

<tt>Monofont words</tt> in a paragraph.

<tt>Monofont passage containing _italics_ and *bold*.</tt>

Rendered HTML:

Monofont words in a paragraph.

Monofont passage containing _italics_ and *bold*.

A single word may be made monofont by a shorthand: prefixed and suffixed plus-signs.

Example input:

+Monofont+ in a paragraph.

Rendered HTML:

Monofont in a paragraph.

Strikethrough

Text may be marked as strikethrough via HTML tag <del> or <s>.

Example input:

<del>Strikethrough words</del> in a paragraph.

<del>Deleted passage containing _italics_ and *bold*.</del>

Rendered HTML:

Strikethrough words in a paragraph.

Deleted passage containing italics and bold.

Character Conversions

Certain combinations of characters may be converted to special characters; whether the conversion occurs depends on whether the special character is available in the current encoding.

Certain strings in RDoc text are converted to links. Any such link may be suppressed by prefixing a backslash. This section shows how to link to various targets.

Note: When marking up code (such as class, module, constant, and method) as “+code+” (for interoperability with other Markdown parsers mainly), any word that refers to a known code object, and is marked up entirely and separately as “monofont”, is also converted to a link.

Note: Occasionally RDoc is not linked to a method whose name has only special characters. Check whether the links you were expecting are actually there. If not, you’ll need to put in an explicit link; see below.

Pro tip: The link to any method is available in the alphabetical table of contents at the top left of the page for the class or module.

See the Note and Pro Tip immediately above.

Protocol http

  • Linked: http://yahoo.com links to yahoo.com.

Protocol https
Protocol ftp
Protocol mailto
Protocol irc

Image Filename Extensions

Link: https://www.ruby-lang.org/images/header-ruby-logo@2x.png is converted to an in-line HTML img tag, which displays the image in the HTML:

Also works for bmp, gif, jpeg, and jpg files.

Note: Works only for a fully qualified URL.

Link: LICENSE at RDoc::RD links to LICENSE at RDoc::RDoc::RD.

Note that spaces in the actual heading are represented by + characters in the linkable text.

Punctuation and other special characters must be escaped like CGI.escape.

Pro tip: The link to any heading is available in the alphabetical table of contents at the top left of the page for the class or module.

See Directives for Organizing Documentation above.

If a section and a heading share the same name, the link target is the section.

Single-Word Text Link

Use square brackets to create single-word text link:

Multi-Word Text Link

Use square brackets and curly braces to create a multi-word text link.

rdoc-ref Scheme

A link with the rdoc-ref: scheme links to the referenced item, if that item exists. The referenced item may be a class, module, method, file, etc.

If the referenced item does not exist, no link is generated and entire rdoc-ref: square-bracketed clause is removed from the resulting text.

rdoc-label Scheme

Simple

You can specify a link target using this form, where the second part cites the id of an HTML element.

This link refers to the constant EXAMPLE_CONSTANT on this page:

With Return

You can specify both a link target and a local label that can be used as the target for a return link. These two links refer to each other:

Thus:

go to addressee

Some text.

return to sender

rdoc-image Scheme

Use the rdoc-image scheme to display an image that is also a link:

{rdoc-image:path/to/image}[link_target]

A relative path as the target also works:

Escaping Text

Text that would otherwise be interpreted as markup can be “escaped,” so that it is not interpreted as markup; the escape character is the backslash ('\').

In a verbatim text block or a code block, the escape character is always preserved:

Example input:

This is not verbatim text.

  This is verbatim text, with an escape character \.

This is not a code block.

  def foo
    'String with an escape character.'
  end

Rendered HTML:

This is not verbatim text.

This is verbatim text, with an escape character \.

This is not a code block.

def foo
  'This is a code block with an escape character \.'
end

In typeface markup (italic, bold, or monofont), an escape character is preserved unless it is immediately followed by nested typeface markup.

Example input:

This list is about escapes; it contains:

- <tt>Monofont text with unescaped nested _italic_</tt>.
- <tt>Monofont text with escaped nested \_italic_</tt>.
- <tt>Monofont text with an escape character \</tt>.

Rendered HTML:

This list is about escapes; it contains:

In other text-bearing blocks (paragraphs, block quotes, list items, headings):

Derived Documentation

RDoc can automatically derive documentation from Ruby code. For demonstrations, see RDoc::Example.

Class

By default, RDoc documents:

Module

By default, RDoc documents:

Method

By default, RDoc documents:

See RDoc::Example#derived_docs_example.

Alias

By default, RDoc documents:

See RDoc::Example#aliased_method.

Constant

By default, RDoc documents:

See RDoc::Example::EXAMPLE_CONSTANT.

Attribute

By default, RDoc documents:

See RDoc::Example#example_attribute.