Last month we shipped Aliki, RDoc’s new default theme. It brought dark mode, better search, and a modern layout to docs.ruby-lang.org and any gem using RDoc 7.0+. That was primarily about the reading experience.

This year I want to focus on the writing experience—and how documentation might need to evolve for the AI era.

Moving toward Markdown

RDoc markup has served Ruby well, but Markdown has become the industry standard. Most developers already know it. RDoc markup, being Ruby-specific, creates unnecessary friction for contributors.

I’ve been working on improving RDoc’s Markdown support to reach feature parity with GitHub Flavored Markdown. Although RDoc has supported Markdown for many years, it was buggy and lacked documentation. So starting this year, I’ve been working on fixing those issues. Some recent changes:

  • GitHub-style heading anchors: Headings now generate lowercase, hyphenated anchors (like #my-heading instead of #label-My+Heading). Markdown links like [link](#my-heading) now work as expected. Legacy anchors are preserved as hidden elements so existing links don’t break.
  • Strikethrough: ~~text~~ now renders properly in Markdown files.
  • Backticks in RDoc markup: Users can now use backticks (`) in addition to + for inline code. This is a common mistake in Ruby core documentation contributions—rather than correcting people, we should just support what they naturally write.
  • Better code block handling: Fixed issues where non-Ruby code blocks were incorrectly getting Ruby syntax highlighting.

I’ve also rebuilt RDoc’s markup documentation to better explain what’s supported in each format.

The above changes have been shipped in RDoc v7.1.0.

The long-term goal is to make Markdown the default for Ruby documentation and help existing RDoc markup projects migrate to Markdown.

RBS integration

Type information is becoming more valuable—both for developers and for AI tools that consume documentation. I want RDoc to support displaying RBS signatures alongside method documentation.

This means integrating inline and external RBS signatures into both HTML and RI output, with dedicated documentation section for type definitions (e.g. type aliases, generic types, etc.).

Documentation for AI

This is more exploratory, but I think documentation tools need to consider how AI agents consume documentation.

One direction is generating LLM-friendly output formats. GitBook’s approach with llms.txt and markdown-only pages is interesting. Markdown is more token-efficient than HTML, and having a single-file documentation dump could be useful for context windows.

Another direction is agent skills that help write documentation. I’ve been thinking about what this could look like for RDoc:

  • Setting up RDoc for a project, from documentation generation to deployment on GitHub pages
  • Writing documentation using RDoc features and directives

Not directly related to RDoc, but I also would like to explore general Ruby skills, like:

  • Navigating common Ruby environment issues (version managers, bundler, etc.)
  • Using ri to look up existing Ruby documentation for more effective Ruby programming

What’s next

The Markdown improvements and documentation overhaul are ongoing. RBS integration is next on the list, targeting RubyKaigi. The AI-related work is something I’ll explore throughout the year as I continue to use these tools myself.

If you’re generating documentation with RDoc and run into issues with any of these newer features, please open an issue.