Introducing Aliki: A Modern Theme for Ruby Documentation

Ruby has always been a joy to write. But for a long time, reading Ruby documentation on docs.ruby-lang.org hasn’t really matched that experience.

Last year, I brought a new look to the Darkfish theme by updating its visuals and improving mobile support. It was a visible improvement, but it wasn’t enough.

So this year, I built something new from the ground up. Starting with RDoc 7.0.0, Aliki is now the default theme for RDoc.

This release also coincides with Ruby’s 30th anniversary and the redesign of ruby-lang.org—a great moment to give Ruby’s documentation a fresh look as we head into the next chapter with Ruby 4.0.

Why a New Theme?

Even after last year’s improvements, I still didn’t enjoy using docs.ruby-lang.org as much as I wanted. Every time I needed to look something up, the experience felt dated.

And it was difficult to further improve Darkfish because:

• It lacks documentation, especially around the original design decisions
• Some of the patterns it uses were outdated
• Some third-party themes build on Darkfish, so updating it too much risks breaking them

RDoc itself added more constraints: It can’t depend on any gem that doesn’t ship with Ruby itself, and it can’t run a modern JavaScript build pipeline.

RDoc was created in the pre-Node.js era and hasn’t evolved with frontend tooling. Adopting modern toolchains would raise the dependency requirements for everyone—Ruby’s documentation generation pipeline, gems like IRB and Reline, and so on.

So all JavaScript, CSS, and HTML had to be written directly—no frameworks, no build tools, no npm packages.

And honestly, given all the constraints, this project wouldn’t have been possible without AI coding agents. Last year, just getting Darkfish’s code block styling right took me hours. It was a struggle for me to implement the look I wanted, and then to make it work with surrounding elements. At that pace, building an entire new theme wasn’t realistic.

This year, however, I discovered that I could try three different UI styles in an hour with AI agents. So I decided to take on the impossible task.

My goal was simple: make docs.ruby-lang.org look modern and actually enjoyable to use.

I collected all the features I wished a documentation site would have, gathered feedback from Rubyists around me, cherry-picked the improvements the community added to Darkfish last year (SEO, search enhancements, etc.), and put them together into a new theme.

Ok, enough of the back stories. Let’s see what Aliki brings:

Search

The old search wasn’t intuitive. It supported fuzzy matching, but getting the sorting right was difficult—searching Arr never actually got you the Array class as the first result.

After a few patch-ups, it was still buggy, so I rewrote it with a new UI:

• On desktop:

• On mobile:

Some notable new features/improvements:

• Case-aware ranking: If you search parse (lowercase), methods show up first. If you search Parser (capitalized), classes and modules come first.
• Fuzzy matching: This existed before, but fuzzy results used to pollute the top of the list. Now we have a smarter ranking system to make sure exact/substring matches show up before fuzzy results.
• Constants included: You can now search for constants, along with classes, modules, and methods.
• Type labels: Each result shows whether it’s a class, module, method, or constant.
• Keyboard support: Did you know you can press / to focus the search bar? This existed in Darkfish too, but I thought it was worth mentioning.

Dark Mode

Aliki has a light/dark toggle. It saves your preference and respects your OS dark mode setting by default.

Layout

The layout has three columns:

• Left sidebar: Navigation for pages, ancestors, methods, and class/module index
• Center: The documentation content
• Right sidebar: A table of contents generated from headings, with the current section highlighted as you scroll

Sidebar sections can collapse. For example, when you’re on a class or module page, the pages section is automatically collapsed so you can focus on the relevant navigation, with page documents still accessible if you need them.

Speaking of pages, I also reorganized the pages list this year. It used to be a long, rather flat list—now pages are grouped and much easier to navigate. In the coming year, we’ll continue improving page documentation so it feels more like a coherent guide rather than a collection of loosely related pages.

On mobile, the layout is a single column with a hamburger menu and a full-screen search modal—same as before.

Code Features

Code blocks now have copy buttons:

C code is now highlighted too:

For Gem Documentation

Aliki works for any gem, not just Ruby core. If you generate documentation with RDoc 7.0+, your users will see this theme automatically.

You can also customize the footer links now. For example, in your .rdoc_options:

footer_content:
  DOCUMENTATION:
    Home: index.html
  RESOURCES:
    GitHub Repository: https://github.com/your/repo
    Issue Tracker: https://github.com/your/repo/issues

This is useful for linking to your gem’s repository, issue tracker, or other resources.

To keep using Darkfish in your project, you can switch back with:

generator_name: darkfish

Acknowledgments

Thanks to @tompng and @earlopain for reviewing the code and helping polish things up.

Try It Out

You can see Aliki at docs.ruby-lang.org/en/master/ or ruby.github.io/rdoc/.

If you find issues or have suggestions, open an issue on GitHub.

What’s Next

Now that reading docs is enjoyable again, the next step for RDoc is to make writing docs enjoyable too.

About the Name

Aliki is my cat. I’m not good at naming things, so I just named the new theme after her.