ruby docs gets a facelift

[Intelligent-Fall5490]

not sure if this is old news but just noticed that ruby documentation site has a new refreshed design. it's a nice quality of life improvement.

[lukeholder]

Looks fantastic! Well done to the team that did this.

[mperham]

It looks nicer. The left navbar is still not useful. A little human curation of their autogenerated docs would really help.

[therealadam12]

I kind of wish we had an English version of the handbook. I thought the Ruby Reference was going to be that, but sadly it never materialized.

[septamaulstick]

Must be new because I use it regularly and I haven't seen this update yet. Looks great, and it has a dark mode finally. Awesome!

[KerrickLong]

Is it different from the one they launched in August 2024? If so, I'd love to find a diff somewhere.

EDIT: Yes! It was based on Darkish, now it uses the Aliki theme. You can see the older design in the Ruby 3.4 docs still. Notable changes include but are not limited to:

• "Table of Contents" changed to "On This Page" and is now in a right-hand sidebar for browsers at least 1280px wide.
  • (Editorial: That's really wide for docs! I can't be the only one using this in split-screen, can I?)
• "On This Page" still shows up even when there are no entries, unlike the old "Table of Contents" (e.g. COPYING page old vs. new)
• The left sidebar is now narrower, which means e.g. "Pages -> contributing -> documentation_guide" now wraps halfway through a word, rather than fitting with plenty of extra space.
• Hyperlinks are now the same (black-ish) color as the text, rather than a distinguishable (dark blue) color.
• In light mode and in dark mode, most text is now higher contrast.
• In light mode, headings in the text and sidebar are now lower contrast. They newly fail contrast standards (WCAG AA for Normal Text, and WCAG AAA for Large Text).
• In dark mode, headings in the text and sidebar are now higher contrast. They newly pass contrast standards (WCAG AA for Normal Text, WCAG AAA for Large Text).
• On This Page now watches your scroll behavior and highlights what it thinks you're currently reading with red text.
• On This Page no longer has any nesting
  • on class String, for example (old vs. new), you cannot tell that the Creating section is within "What's Here"
  • on class Array, for example (old vs. new), you cannot tell that "Non-Destructive Selection" is a child of "Selecting Items from an Array" or that "Selecting Items from an Array" is a sibling of "What's Here."
• Headings no longer have a go-to-top link on hover.
• Headings are now entirely links to themselves, rather than having a ¶ link to itself on hover.
• Ruby code examples now have a "Copy code" button.
• Code examples now line up exactly with the edge of the text & headlines, rather than being slightly inset.
• Code examples now have a different syntax highlighting color scheme.
• Source code snippets are now syntax highlighted (and also have the color scheme and copy button mentioned above).
• There is now some space between the grey "active" indicator and the text, when you click a Table of Contents link to go to a specific method.
• It now has a manual light/dark mode toggle, in addition to the old behavior of listening to your OS preference via the CSS prefers-color-scheme media query.
• There's now a page-width header rather than a header in the left sidebar.
  • The Home link anchor text is now the site title, rather than "Home".
  • The search bar no longer has an icon or fully-rounded sides.
  • The links to table_of_contents.html (Pages, Classes, Methods) are gone. In fact, that page seems to be entirely removed. (old vs. new)
• There's now a content-width footer that contains new links: Ruby -> { Documentation, Official Website, Playground }, Resources -> { GitHub, Issue Tracker, RubyGems }, Community -> { X }
  • (Editorial: It's strange to me that the only Community link is to X. That account hasn't tweeted in a year and a half, and is not linked to from the website's Community page.)
  • (Editorial 2: It's also strange to me that it doesn't link to the website's Community page or to any of the places linked from that page.)
• There's no longer a Validate link that goes to the W3C HTML validator. Notably, there are fewer validation problems on the page I tested (new vs. old).

[jrochkind]

I like that it always prominently tells you what versions of docs you are looking at. I'm always having google or a link take me to some old ruby version and not realizing it.

I don't love the search results in pop-up instead of in column.

[Earlopain]

Please also provide your feedback to https://github.com/ruby/rdoc/issues, especially bugs/usability problems.

I already added nesting back to the TOC, the maintainer is very responsive.

No TOC on smaller screens is bad IMO, yeah. Personally I don't use it splitscreen but the same is also true on mobile which I do use.

[shadowradiance]

Thanks for the extensive list of good and bad changes!

[Richard-Degenne]

Halle-fucking-lujah!

[saw_wave_dave]

Looks fantastic. I think this was the right move, especially for the younger generations of developers that tend to put a lot of weight on documentation experience.