RDoc is Ruby's own documentation generator, and it is changing markup

The rdoc and ri tools come with Ruby itself

RDoc is the documentation system for Ruby, and the README describes it in one line: it produces HTML and command-line documentation for Ruby projects, and it includes the rdoc and ri tools for generating and displaying documentation from the command line.

The two tools cover opposite ends of the same job. rdoc generates, ri displays. That pairing matters for adoption: if you already write Ruby, rdoc is almost certainly already on your machine, which removes the usual objection to a documentation tool, the dependency and the version skew.

The repository is the Ruby project's own, hosted at ruby.github.io/rdoc/, and the topic tags list documentation-tool, hacktoberfest and ruby. Recent releases are v7.0.4 on 2026-05-12, v8.0.0 on 2026-06-26 and v8.1.0 on 2026-09-28, so major versions arrive every couple of months and the current major is eight.

The audience is broad. Anyone publishing a gem, an internal library or a command line tool needs to describe its API, and the alternative to using the bundled tool is choosing and operating a separate one.

File extensions pick the parser, and directories are scanned recursively

The dispatch mechanism is by file extension, and the README is explicit about it.

File names ending .rb and .rbw are assumed to be Ruby source. Files ending .c are parsed as C files. Files ending .rbs are parsed as RBS signature files. Everything else is assumed to contain just Markup-style markup, with or without leading # comment markers. When directory names are passed, they are scanned recursively for C, Ruby and RBS source files.

That last sentence has a practical consequence worth internalising. A single command over a project directory will pick up every Ruby, C and RBS file below it, including files in a vendor directory or a test fixture, unless the .document file narrows the list. The README describes that file as living in the project root and containing a list of file and directory names, with comment lines starting with #.

So the discovery set for a documentation build is a decision, not just a directory scan. The .document file in this repository is pointed to as the example to follow.

RBS signature files can extend the documentation of Ruby objects

RBS is the type signature format for Ruby, and the README describes how RDoc treats those files.

RBS files can document classes, modules, methods, attributes and constants. When RBS declarations match objects that are already documented from Ruby source, their comments and type signatures extend the existing documentation.

That is the interesting bit. It means the type signature file is not only a source of machine-checkable types but also a documentation source, so a project that keeps types in separate .rbs files gets two things from one file. A method that is only visible through a signature gains a description, and a method that already has a comment gains a type.

The trade-off is that it splits the description of an API across two places. Ruby source comments and .rbs files can both claim to describe the same method, and the README's wording, that RBS declarations extend the existing documentation, leaves the precedence between a source comment and a signature comment unstated in what is available here.

The .rbs extension also means a plain rdoc run over a project will pick these files up automatically, whether or not you intended them to be part of the documentation set.

Three ways to generate: the command, the rake task and the API

The command line entry point takes options and a list of names.

rdoc [options] [names...]

Running it with no arguments generates documentation for all the Ruby and C source files in and below the current directory, storing the result in a documentation tree starting in the subdirectory doc. To put the documentation for the primary file on the index page, the README suggests passing the main file explicitly.

rdoc --main README.md

There are two other entry points. The first is rake, through the RDoc::Task class, which is how a project wires documentation generation into its build. The second is the library API, which the README shows as a short script.

require 'rdoc/rdoc'

options = RDoc::Options.new
options.files = ['a.rb', 'b.rb']
options.setup_generator 'aliki'
# see RDoc::Options

rdoc = RDoc::RDoc.new
rdoc.document options
# see RDoc::RDoc

The programmatic form is the one to reach for in a custom pipeline. It lets you set the file list explicitly, which removes the accidental-discovery problem of the directory scan, and it lets you pick the generator by name, here aliki, which is the default theme.

RDoc markup is being retired in favour of Markdown

The most consequential change in the project is a change of markup, and the README states it plainly: RDoc markup is currently the default format for Ruby and C files, but the plan is to retire it in favour of Markdown.

Markdown support is described as actively being improved, and once it reaches feature parity with RDoc markup it becomes the default format. For standalone documentation files, the recommendation is to write .md files rather than .rdoc files. RD and TomDoc are called legacy formats and their use in new projects is strongly discouraged.

The format can be chosen at three levels. Per file, a :markup: directive at the top of a Ruby file. Per project, a .rdoc_options file in the project root.

markup: markdown

Or on the command line.

rdoc --markup markdown

The feature table in the README explains why the switch matters. RDoc markup uses = for headings, *word* for bold, _word_ for italic and +word+ for monospace, and it has no support for tables or footnotes. Markdown supports both tables and footnotes, and adds fenced code blocks and strikethrough.

Both formats support directives such as :nodoc:, and cross-references are automatic in either.

Aliki is the default theme and Darkfish will go in v9.0

RDoc ships with two built-in themes, and one of them is on its way out.

Aliki is the default, described as a modern, clean theme with improved navigation and search. Darkfish is the classic theme, marked deprecated, and the README says it will be removed in v9.0. It can still be selected on the command line.

rdoc --format darkfish

Or in the .rdoc_options file.

generator_name: darkfish

That removal notice is the kind of detail that matters when you are picking a documentation tool for something that has to keep building. If your project pins Darkfish for a specific reason, it is on borrowed time, and the migration target is Aliki.

There are also community-maintained themes, with the README linking rorvswild-theme-rdoc and hanna, the latter a fork maintained by Jeremy Evans. The instruction is to follow each theme's own README for usage. These are separate repositories with separate maintenance, so a theme you rely on is a dependency to track like any other.

The theme is also what the live server uses, which matters for the next section.

The preview server parses once and serves from memory

RDoc now includes a built-in server for previewing documentation while you edit source files.

rdoc --server

This starts a server at http://localhost:4000, and a different port can be given.

rdoc --server=8080

There is a rake task form as well.

rake rdoc:server

The README explains the mechanism: it parses all source files on startup and serves pages from memory using the Aliki theme, then watches for changes and auto-refreshes the browser. The section describing this is cut off partway through, so the details of the background watching beyond the auto-refresh are not described in what is available.

This is the feature that changes the daily experience of using RDoc. Documentation for a library is usually written while the library changes, and a rebuild-and-reopen loop is what makes people postpone writing docs. Serving from memory and refreshing on save removes the rebuild from the loop.

It is also worth knowing that the coverage tooling exists alongside all this. The README describes running rdoc -C lib to get a documentation coverage report, and rdoc -C1 lib to include parameter names in that report, which is how you find the methods nobody ever described.

Editorial conclusion

RDoc suits Ruby library authors who want documentation built with the same toolchain the language already ships, with no extra dependency to install and no hosting decision to make. It does not suit a team that needs Markdown tables, footnotes or fenced code blocks today, since RDoc markup is the default for Ruby files and Markdown support is still being improved toward parity. Before you standardise on it, read the markup comparison table and decide which format your contributors will actually write, check whether your Ruby source is documented in comments or in RBS signature files, and read LICENSE.rdoc, since the licence on the repository is a custom one that GitHub cannot classify.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. ruby/rdoc on GitHub