Ruby Deserves Better Documentation Tools

sanif — Tue, 27 Jan 2026 01:16:21 +0000

I maintain a Ruby gem. When it came time to write documentation, I went looking for the right tool.

Jekyll was the obvious choice. It's Ruby-native, battle-tested, and powers GitHub Pages. But Jekyll is built for blogs. Making it work for documentation meant hunting for themes, configuring layouts, and adapting blog-oriented templates to fit technical content. It's possible, but it's work.

I ended up using VitePress.

VitePress Is Excellent. But It Felt Off.

VitePress gave me exactly what I wanted: fast builds, beautiful output, search that just works. My docs looked professional in minutes.

But there I was - a Ruby gem with a JavaScript documentation site. It worked fine. It just felt like I was borrowing someone else's tools because my own ecosystem didn't have what I needed.

The Gap

JavaScript developers have VitePress, Docusaurus, and Starlight. Python has MkDocs with the Material theme. These are purpose-built for documentation. You run a command, write Markdown, and get a professional docs site with search, dark mode, and components like tabs and callouts.

Ruby has excellent tools, but they solve different problems:

YARD & RDoc - API documentation generated from code comments. Perfect for that use case, but not for writing guides and tutorials.
Jekyll, Bridgetown, Middleman, Nanoc - Capable static site generators, but general-purpose. You'd need to build docs-specific features yourself.

If you want a documentation site with minimal setup, your options are: configure a general-purpose SSG, or reach for a tool from another ecosystem.

That felt like a gap worth filling.

Docyard

Docyard is a Ruby gem for building documentation sites. The goal: make it as easy to create docs in Ruby as it is in JavaScript or Python.

gem install docyard
docyard init my-docs
cd my-docs
docyard serve

That gives you:

Search - Full-text, keyboard navigation, works offline
Dark mode - Follows system preference
Syntax highlighting - All the languages you'd expect
Components - Tabs, callouts, code groups, steps, accordions
Sensible defaults - Clean typography, responsive layout

No themes to configure. No build pipeline to set up.

Here's what a callout looks like in Markdown:

:::note
This is a note callout. There's also `tip`, `warning`, and `danger`.
:::

That renders as a styled callout box. Same pattern for tabs, steps, and other components - all plain Markdown syntax.

See It

The Docyard documentation is built with Docyard.

Check out Docyard

Try the search. Toggle dark mode. That's what you get out of the box.

What's Next

Docyard is at v1. It handles the core use case well, but there's more to build.

It's free and open source.

sanifhimani / docyard

Generate beautiful documentation sites from Markdown

Markdown to docs in seconds. No Node.js required.

Docs · Quickstart · Changelog

Install

gem install docyard
docyard init
docyard serve

Open localhost:4200. Edits reload instantly.

Example

:::note
Requires Ruby 3.2 or higher.
:::

:::tabs
== macOS
brew install ruby

== Linux
sudo apt install ruby-full
:::

Callouts, tabs, steps, cards, code groups, accordions, and more. See all components

Build

docyard build

Static HTML, search index, sitemap, and social cards in dist/. Deploy anywhere.

Docs

docyard.dev is built with Docyard.

Contributing

See CONTRIBUTING.md.

License

MIT

View on GitHub

If you try it on a project, I'd like to hear how it goes - especially the rough edges. Issues and feedback welcome.

DEV Community: sanif