RoRvsWild RDoc theme
As much as we enjoy Ruby, we have long thought the Ruby documentation could use more love. We could contribute and give some.
So we started to investigate the RDoc template generator, which powers the Ruby documentation, to see how it worked and what we could do with it. We finally made quite a few changes.
Layout and navigation
We updated the layout and structure of the page to make it easier to navigate the documentation.
We added a fixed top bar with the project title and moved the search field there to make it always reachable. The search result benefits from more space than when they were in the sidebar.
On larger screens, we’ve hidden the navigation toggle and made the main navigation always visible. The main navigation content is now always the same on all documentation pages. It lists all the classes and pages. It’s now the documentation’s table of contents, and we could eliminate the previously separated page used for this function.
On the right side of the page, we’ve added contextual navigation that depends on the content shown. It can list metadata, such as the class ancestors, instead of just the parent. It also lists shortcuts to the various sections of the page and methods, as it is now commonly the case in documentation websites.
Typography
We wanted to improve the readability. We simplified the typography and changed the open-source fonts used. Instead of 3 families, we only use 2: Inter for text and Monaspace Neon for code. We also use fewer weights, getting rid of light versions that tend to be hard to read on screens. We used a modular scale to make titles look more harmonious. We adjusted some spacing and alignments too.
Colors
We’ve updated the color scheme to use Oklch and improved the contrast and harmony. You may recognize RoRvsWild colors. We changed the primary color from green to red because the rubies are red. We used that primary color more sparingly, only for content links. We also added a dark mode. There is no button to switch or preferences to set, but it respects your system settings and eyes at night.
New default theme?
Two week ago, we submitted a PR hoping it would eventually become the new default theme, dreaming to contribute to the Ruby documentation.
While it was received with enthusiasm and was “ticking the boxes”, for some reason, the RDoc maintainers decided to use it as some kind of roadmap instead and to pick some of the changes and integrate them one by one in the old theme.
As much as we are happy the documentation system of our beloved programming language is evolving for the better, our version is still a few steps ahead. We spent a lot of time on it and have plans to improve it.
Maintainers get to choose the gifts they give and accept to receive. It can sometimes be frustrating and feel like a total waste of time, but there is often a plan B.
Introducing RoRvsWild RDoc theme gem
The alternative plan was suggested by Marco Roth when we told him we were working on this during Friendy.rb: release it as a Ruby gem. It comes with significant advantages: you get all the improvements now without having to hope they eventually get integrated into RDoc, and we are free to make it evolve the way we want without waiting for approval.
We just did that, and you can find the gem on Github.
What do you think?
We see some room for more refinements, but what we have is quite an improvement over what is currently used, even if it’s now evolving.
We didn’t list all the small details in this post, but you can compare the before and after and find some.
Does it make reading the documentation more enjoyable for you too? We’d be happy to hear from you on Mastodon, Twitter, or directly in the GitHub repository.
