simple-navigation builds multi-level menus for Rails, Sinatra and Padrino

One gem for three Ruby web frameworks

Simple Navigation is a Ruby library for creating navigations, with multiple levels, for Rails, Sinatra or Padrino applications. The description is precise about the output as well: you can render your navigation as an HTML list, a link list or breadcrumbs.

The audience is a Ruby developer with a multi-level site structure who does not want to hand-maintain a nested list in every template. The framework list is the interesting part. Rails, Sinatra and Padrino are three different stacks with different conventions about where a route definition lives and how a controller is named, and supporting all three from one library means the navigation is derived from something they have in common rather than from a per framework template.

The compatibility claim is unusually broad. The README says it runs with all Ruby versions, including Ruby 2.x. For a gem in this space that is a statement about the code, because Ruby 2.x syntax constraints are tight, and it also means the library does not assume modern language features, which in turn keeps it usable in the long-lived applications where navigation changes least often.

The licence is MIT, with the copyright line reading Copyright 2026 codeplant GmbH, released under the MIT license, and the default branch is master. The last push to the repository was on 2026-08-09, and the repository publishes no GitHub releases, so the version history lives in the CHANGELOG.md and in the gem's own version numbering rather than in tags.

Three output shapes from the same navigation structure

The three rendering options are the part of the API worth understanding, because they are the difference between a navigation helper and a menu builder.

An HTML list is the plain output, the nested ul and li structure that a stylesheet turns into a menu. A link list is the flat alternative, a set of anchors for the same items, which is what you want when the menu is rendered as a set of links in a bar or in a footer rather than as a tree. Breadcrumbs are the third shape, and they are the one that shows what a navigation library buys you, because a breadcrumb trail is a path through the hierarchy rather than a rendering of the whole thing, and getting it right by hand in every view is exactly the kind of repetition a library removes.

All three come from the same source, the navigation you declared, which is the point. The alternative to this library is not another gem, it is writing the markup yourself in each template, and that has two costs. The first is repetition, since the list is duplicated in every view that shows it. The second is drift, since a new section has to be added in every copy, and the copy that gets missed is the one that shows up as a bug on one page of the site.

A library that derives the navigation from the application also moves the cost. You declare the structure once, and adding a page means adding it to the structure rather than to a template. The trade is coupling: the navigation is expressed in terms of the framework's routing and controller conventions, so the library is not a standalone HTML helper you could drop into any Ruby project, and the README does not document what happens when two applications use conflicting route names.

The practical advice for a team evaluating it is to look at the demo rather than at the feature list, because what a navigation library produces is entirely a function of how it is configured.

Appraisal runs the suite against every supported framework

The contributing section tells you how to run the tests, and the method is the interesting part.

To run the test suite locally against all supported frameworks, the README gives three commands:

bundle install
bin/appraisal bundle install
bin/appraisal rspec
bin/appraisal rspec ./spec/requests/users_spec.rb

And to target the test suite against one framework, it gives two more:

bin/appraisal rails_8.1 rspec
bin/appraisal rails_8.1 rspec ./spec/requests/users_spec.rb

That is the appraisal tool, which manages a gemfile per supported framework, and the repository layout confirms it with a gemfiles/ directory, an Appraisals file at the root and bin/ holding the executable. The rails_8.1 name in the example is the appraisal name for one combination, and the fact that the README offers both the all frameworks run and the single framework run tells you the library is tested against more than one stack and that the differences between them are worth testing.

The spec/ directory holds the tests, and the example path points into spec/requests/, so the suite is organised around request level tests rather than only unit tests of the helper objects. The .rspec file at the root configures the runner, the Guardfile is the file watch setup, and the Rakefile is the task entry point.

For a contributor, the workflow is the one the README describes in a single line: fork, fix, then send a Pull Request. For a user, the practical value of the appraisal setup is that it is a signal about which framework versions the library actually supports, since a matrix that is not exercised tends to rot.

Documentation in the wiki, in RDoc, and in a demo project

The documentation is split across three places, and each answers a different question.

The wiki holds the complete documentation, and the README sends you there first. For the API reference, the project publishes RDoc, hosted on RubyDoc.info, with the frames view linked. And if you need to generate the RDoc files locally, the README says to check out the repository and call the rake rdoc task in the project's folder.

That last point is worth noting for a library, because it means the API documentation is generated from the source comments with a standard tool rather than maintained as a separate artifact, and a contributor can produce the same pages the project publishes.

The third resource is the demo, whose source code is available on GitHub in a separate simple-navigation-demo repository. For a navigation library that is the most useful of the three, because the output of a navigation is a piece of HTML whose quality depends entirely on how it is configured, and reading a working example tells you more in a few minutes than a description of the options does.

Questions and feedback have their own place, the project's group on Google Groups, and the README invites people to come and talk there. That is an old fashioned arrangement and it has an advantage over a tracker for a library like this, where the questions are about how to structure a navigation rather than about a specific bug.

The Ruby version the project develops against is pinned in a .ruby-version file at the root, which is the file to look at if you need to know what the maintainers are building against.

Generators, a Rubocop todo file and a changelog

The repository listing is short and each entry has a purpose.

The generators/ directory means the gem can create files into a host application, which for a navigation library is usually the configuration that declares the structure and the templates that render it. The lib/ directory holds the library itself, and the spec/ directory the tests. The Gemfile and simple-navigation.gemspec are the packaging, and the Rakefile and Guardfile are the development tasks.

Two files are worth a second look. There is a .rubocop.yml for the style configuration and a .rubocop_todo.yml beside it. A todo file in that pair is a record of style offences that are known and deferred, and its presence tells you that the project runs Rubocop but has accepted a set of exceptions rather than claiming a clean sheet. That is a normal and honest arrangement, and it is also something to look at when you want to know how much of the code is in the shape the maintainers want it.

The CHANGELOG.md at the root is the upgrade path. Since the repository publishes no GitHub releases, the changelog is where you find out what changed between gem versions, and for a library that has been in use long enough to have a version history, that file is the thing to read before a version bump rather than after one.

The other directories are the automation. The .github/ directory holds the workflows, and the build status badge in the README points at a workflow called ci.yml running on the master branch. The coverage badge points at Coveralls, so the test coverage is tracked over time rather than being a claim in a badge that nobody checks.

Put together, this is the profile of a mature, slowly moving library. It supports several frameworks, it tests across them, it documents itself in the standard places, and it does not churn.

What it is not, and the trade a user makes

Two boundaries are worth stating.

The first is scope. A navigation library that derives its structure from the application's routes and controllers is coupled to those frameworks, and the coupling is the price of not repeating the markup. If your navigation is a static list of four links in a footer, or if your application is not built on Rails, Sinatra or Padrino, this library does much more than you need, and a few lines of markup in a layout template would serve you better.

The second is the version line. The README says the library runs with all Ruby versions including Ruby 2.x, and the repository pins a specific .ruby-version. For a long-lived application that is a gift, since the navigation is the part of the site that changes least and the part most likely to be dragged along by a framework upgrade. For a new project on a current Ruby, it also means you are adopting a library whose own development is anchored to an older runtime, which is worth checking against your application before you commit to it.

And there is the honest gap in the documentation. The README is short, it points at a wiki for the complete documentation, and it does not describe how the library handles the cases where applications differ, such as a route that does not map cleanly onto a menu item or two controllers with the same name in different namespaces. The wiki is the place to look for that, and the demo repository is the place to look for what the output actually looks like.

So the adoption decision comes down to a simple question. If you have a multi-level navigation in a Rails, Sinatra or Padrino application, and you would rather declare it once than edit every template, this library is a good fit and the demo will tell you within minutes. If your navigation is flat, or your stack is not on the list, write the markup yourself.

Editorial conclusion

Adopt simple-navigation if you are building a Rails, Sinatra or Padrino application with a multi-level navigation and you want one library to render it in more than one shape, including breadcrumbs, without hand-maintaining the list in every template. Do not adopt it if your navigation is a single flat menu, since the multi-level machinery and the framework coupling are not needed for that, and do not adopt it expecting recent Ruby releases to be the target, because the README says it runs with all Ruby versions including the 2.x series and the pinned .ruby-version file is what your project will follow. Before you upgrade it, read the CHANGELOG.md in the repository and run the appraisal suite across the frameworks, because the gem supports several and the README does not describe its behaviour differences between them.

Frequently asked questions

Official sources

1. codeplant/simple-navigation on GitHub
2. Issues
3. License: MIT
4. README