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.
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
Docyard
Beautiful documentation sites from Markdown. Fast, simple, no configuration required.
Quick Start
gem install docyard
docyard init my-docs
cd my-docs
docyard serve
Open http://localhost:4200 and start writing.
Documentation
Visit docyard.dev for the full documentation.
Contributing
See CONTRIBUTING.md for guidelines.
License
If you try it on a project, I'd like to hear how it goes - especially the rough edges. Issues and feedback welcome.
Top comments (0)