Sidenotes

Structured YAML/JSON schema annotations for Rails models, as sidecar files, not inline comments.

Sidenotes generates metadata files alongside your Rails models, giving you rich schema information without cluttering your source files. IDEs, editors, and tooling can consume these files to surface column types, indexes, associations, and more.

Why Sidenotes over annotate?

	annotate	sidenotes
Output	Inline comments in model files	Separate sidecar files
Git noise	Every schema change touches model files	Annotation files can be gitignored
Format	Plain text	Structured YAML/JSON
Machine-readable	No	Yes; IDEs and tools can parse it
Merge conflicts	Frequent on model files	None, annotations are local
Customizable sections	Limited	Columns, indexes, associations, FKs, constraints, metadata

Installation

Add to your Gemfile's development group:

group :development do
  gem "sidenotes"
end

Then run bundle install and generate annotations:

bundle install
rake sidenotes:generate

That's it. Sidenotes works with sensible defaults and no configuration.

Optional setup

If you want to customise the configuration, run the install generator:

rails generate sidenotes:install

This creates config/initializers/sidenotes.rb (guarded with return unless defined?(Sidenotes) so it's safe in production) and adds .annotations/ to your .gitignore.

If you'd prefer to commit your annotations, skip the gitignore step:

rails generate sidenotes:install --no-gitignore

Usage

Generate annotations for all models

rake sidenotes:generate

Generate for a single model

rake sidenotes:model MODEL=User

Remove all annotation files

rake sidenotes:clean

Example output

Running rake sidenotes:generate creates .annotations/user.yml:

# Generated by Sidenotes v0.1.0 on 2026-04-08 12:00:00 UTC
# Do not edit manually - regenerate with `rake sidenotes:generate`
---
User:
  metadata:
    table_name: users
    primary_key: id
    enums:
      role:
      - member
      - admin
      - moderator
  columns:
  - name: id
    type: integer
    nullable: false
  - name: name
    type: string
    nullable: false
  - name: email
    type: string
    nullable: false
    limit: 255
  - name: role
    type: string
    default: member
    nullable: true
  indexes:
  - name: index_users_on_email
    columns:
    - email
    unique: true
  associations:
  - type: has_many
    name: posts
    foreign_key: user_id
  - type: has_one
    name: profile
    foreign_key: user_id
  foreign_keys: []

Configuration

# config/initializers/sidenotes.rb
return unless defined?(Sidenotes)

Sidenotes.configure do |config|
  # Directory for annotation files (relative to Rails root)
  config.output_directory = ".annotations"

  # Output format: :yaml (default) or :json
  config.format = :yaml

  # Sections to include
  # Available: :columns, :indexes, :associations, :foreign_keys,
  #            :check_constraints, :metadata
  config.sections = %i[columns indexes associations foreign_keys metadata]

  # Where to look for model files
  config.model_paths = ["app/models"]

  # Exclude models by name or pattern
  config.exclude_patterns = [
    "ApplicationRecord",
    /^HABTM_/,
    /^ActiveStorage::/
  ]
end

Configuration reference

Option	Default	Description
`output_directory`	`".annotations"`	Where annotation files are written
`format`	`:yaml`	Output format (`:yaml` or `:json`)
`sections`	`[:columns, :indexes, :associations, :foreign_keys, :metadata]`	Which sections to include
`model_paths`	`["app/models"]`	Directories to scan for models
`exclude_patterns`	`[]`	Strings or regexps to exclude models

Namespaced models

Namespaced models are written to subdirectories matching their namespace:

Admin::User → .annotations/admin/user.yml
Api::V2::Widget → .annotations/api/v2/widget.yml

IDE integration

VS Code

The companion sidenotes-vscode extension reads .annotations/ files and displays schema information inline as you edit models. Hover over a model name to see its columns, or use the sidebar panel for a full schema overview.

Search for "Rails Sidenotes" in the VS Code marketplace.

JetBrains (RubyMine, IntelliJ)

The sidenotes-jetbrains plugin provides the same inline schema display for JetBrains IDEs. Install it from the JetBrains Marketplace.

Other editors

The structured YAML/JSON format makes it straightforward to build integrations for any editor. The schema is stable and documented; see the example output above for the full structure.

Requirements

Ruby >= 3.1
Rails >= 6.0

Development

git clone https://github.com/1stvamp/sidenotes-ruby.git
cd sidenotes
bundle install
bundle exec rspec

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/1stvamp/sidenotes-ruby.

License

The gem is available as open source under the terms of the MIT License.

sidenotes

Runtime