rails-footnotes for Rails debugging and editor links

rails-footnotes targets local Rails request debugging

rails-footnotes addresses a narrow Rails development problem: a rendered page normally gives little direct visibility into the request being processed or the application code that produced it. The gem appends footnotes containing sessions, request parameters, cookies, the filter chain, routes, environment data, queries, and log information. It also converts file references, including backtrace lines, into links handled by a local editor URL scheme.

The intended audience is Rails application developers who want debugging information without leaving the current page. This is especially relevant during local development, when the application, source tree, and editor usually run on the same machine. The repository describes the project as “Rails 7 Footnotes,” but the documented installation uses the standard Rails generator and Bundler workflow rather than a separate application installer.

The feature is not limited to a single static debug panel. Hooks can add or remove notes conditionally for particular controllers and actions, while custom note classes can present application-specific values. That flexibility is useful, but it also means the resulting page depends on initializer code, editor configuration, and the note classes installed by the application.

How rails-footnotes assembles page diagnostics

The documented extension path has three parts. A developer creates a class under `Footnotes::Notes`, implements the methods described by `abstract_note.rb`, and adds its symbol to the active `Footnotes::Filter.notes` array. Each note can decide whether it applies to a request, provide a title, and return escaped content. A note whose `valid?` method returns false is not displayed.

Before and after hooks run around footnote evaluation. The initializer receives the controller and filter, so application code can select notes based on the controller class and action. The README shows this pattern for a `Message` index action and a `Profile` edit action. This mechanism makes the panel selective without changing note classes globally.

By default, the active note list is:

f.notes = [:session, :cookies, :params, :filters, :routes, :env, :queries, :log]

Setting that list to an empty array suppresses the notes themselves. The documentation says the supporting CSS and JavaScript will still be included. A separate request parameter, `params[:footnotes] = 'false'`, is documented as the way to remove all rails-footnotes content from a page.

By default, the panel is inserted immediately before `</body>`. An application can place `<div id="footnotes_holder"></div>` in a view, after which rails-footnotes uses that element as its holder instead. Other documented presentation controls include `f.no_style`, `f.lock_top_right`, `f.font_size`, and `f.multiple_notes`.

Installing rails-footnotes and generating its initializer

The README documents installation through Bundler, followed by the Rails generator. First add the gem to the application's `Gemfile` with `bundle add rails-footnotes`.

bundle add rails-footnotes

Bundler updates the application dependency set. The next documented command installs the resolved gems.

bundle install

After dependencies are available, run the generator from the application root:

bin/rails generate rails_footnotes:install

The README states that this creates an initializer containing default configuration and examples. A first real use is to open a Rails page after starting the application and inspect the footnotes appended near the end of the HTML. The default list includes request and application diagnostics, so the expected first result is a panel with those note types unless application configuration changes the list.

The installation does not automatically select an editor other than the documented default of TextMate. If the developer's workflow depends on another editor, the initializer remains the place where the URL prefix must be changed.

Editor URL schemes expose source and location details

File links are built from a configurable prefix. The default targets TextMate, while the README documents URL forms for MacVim and Sublime Text 3. A prefix must contain `%s` for the filename, the first `%d` for the line number, and the second `%d` for the column number. The README warns that their textual order must remain filename, line, then column. A URL that places `%d` before `%s` raises an error according to the documentation.

For example, MacVim uses this prefix in `config/initializers/rails-footnotes.rb`:

f.prefix = 'mvim://open?url=file://%s&line=%d&column=%d'

Sublime Text 3 uses the documented `subl` scheme:

f.prefix = 'subl://open?url=file://%s&line=%d&column=%d'

The exact behavior depends on the editor's URL handler and on filesystem paths visible from the machine running that handler. This is more than a display preference. A correct prefix creates links, but a mismatched path can send the editor to a nonexistent local file.

Backtrace links, session values, parameters, cookies, environment entries, filters, routes, and queries are all debugging information. The README does not document authentication for these notes, role checks, redaction policies, or a supported production configuration. It should therefore not be inferred that the default diagnostics are safe to expose on a public deployment.

Containers require explicit editor path translation

rails-footnotes cannot directly open files from a host editor when the application and source paths exist inside Docker, Vagrant, or another virtual machine. The README identifies the cause precisely: generated links point to the virtual machine's directory, while the editor runs on the native machine. Its documented remedy is a lambda prefix that rewrites the filename before constructing the editor URL.

The README's example replaces the `/docker` prefix with a macOS project path:

f.prefix = ->(*args) do
  filename = args[0].sub '/docker', '/Users/name/projects/myproject'
  "subl://open?url=file://#{filename}&line=#{args[1]}&column=#{args[2]}"
end

This is a literal path substitution, not a general remote-development protocol. The developer must adapt it to the actual mounted source directory and editor scheme. Changing a container working directory can invalidate the substitution even when the application still runs normally. The README gives no alternative for multiple mounts, Windows host paths, changing user names, or remote machines.

That limitation is significant for containerized Rails teams. rails-footnotes can still display diagnostics, but one of its most useful local conveniences depends on keeping the guest path and host path aligned.

Custom notes add flexibility and application coupling

Custom notes turn the built-in panel into an application extension point. The README's `CurrentUserNote` reads `@current_user` from the controller, stores it during initialization, returns a title based on the user's name, reports validity based on whether the user was found, and escapes `inspect` output for the fieldset. The corresponding initializer entry is:

f.notes += [:current_user]

The example is small, but it illustrates the maintenance boundary. A custom note executes application code during page rendering and may depend on controller instance variables. If that variable is absent or changes shape, the note must reject or represent the value correctly. The example's `title` assumes `@current_user` has a `name`, while `valid?` checks only whether the object exists, so loading the class alone does not guarantee compatibility with every possible user object.

The README directs developers to `lib/rails-footnotes/abstract_note.rb` for the required methods, but the repository has no GitHub releases. Its last push was on 2026-10-13, which is recent, although push recency alone does not establish compatibility across future Rails versions. Upgrade review must therefore account for changes in controller rendering, custom note classes, initializer keys, and application assumptions.

The MIT license permits use, modification, distribution, and sublicensing subject to its conditions. The repository does not present the MIT license as legal advice or document a separate warranty and support policy.

rails-footnotes differs from request inspectors and isolated debugging tools

A browser-based Rails inspector commonly focuses on request parameters, headers, cookies, response data, or sessions in a separate interface. rails-footnotes takes a narrower route by embedding selected diagnostics directly into the application's rendered HTML. It also adds a Rails-specific connection to filters, routes, queries, logs, backtraces, and editor-opening URLs. That makes it convenient when the goal is to inspect the same page while debugging, but it means the information travels as part of normal page content.

A source-level debugger offers richer stepping, breakpoints, stack inspection, and expression evaluation, while rails-footnotes mainly provides links from page information back to files. The README does not claim breakpoint support, remote debugger sessions, or execution control. Developers who need to pause at a particular instruction should use a debugger rather than expect this panel to replace one.

The closest trade-off is therefore between context and exposure. rails-footnotes puts debugging context in the current HTML and offers direct editor navigation, but it does not document controls for filtering sensitive values or limiting notes by role. A separate inspector may make access boundaries clearer if it provides them. The README does not provide such a policy, so application and environment controls remain the deciding factor.

Editorial conclusion

Rails developers working locally should adopt rails-footnotes when request diagnostics, SQL visibility, filter inspection, and editor navigation justify adding development-page instrumentation. Developers needing proven production behavior, a formal support policy, or release artifacts should check those gaps first. Before enabling it, verify that every target environment excludes diagnostic HTML and that editor paths from containers or virtual machines map to the developer's filesystem.

Frequently asked questions

Official sources

1. indirect/rails-footnotes on GitHub
2. Issues
3. License: MIT
4. README