Action Text

Active contributors: rafaelfranca, dhh, jonhefner

Purpose

Action Text adds rich text content to Rails models, with the Trix WYSIWYG editor on the client side and an Active Record-backed model on the server. Embedded attachments (images, files) are stored via Active Storage. ~2,600 lines of lib/ Ruby plus an editor-side JS bundle.

Directory layout

actiontext/
├── app/
│   ├── helpers/action_text/
│   ├── javascript/                       # @rails/actiontext source
│   ├── models/action_text/
│   │   ├── encrypted_rich_text.rb
│   │   ├── record.rb
│   │   └── rich_text.rb
│   ├── views/action_text/
│   └── views/active_storage/             # Override partials for embedded attachments
├── config/routes.rb
├── db/migrate/                           # action_text_rich_texts table
├── lib/
│   └── action_text/
│       ├── attachable.rb / attachables/
│       ├── attachment.rb / attachments/
│       ├── attachment_gallery.rb
│       ├── attribute.rb                  # has_rich_text :body
│       ├── content.rb                    # ActionText::Content (HTML wrapper)
│       ├── editor/                       # Trix and (newer) ProseMirror integration
│       ├── encryption.rb
│       ├── engine.rb
│       ├── fixture_set.rb
│       ├── fragment.rb
│       ├── html_conversion.rb
│       ├── markdown_conversion.rb
│       ├── plain_text_conversion.rb
│       ├── rendering.rb
│       ├── serialization.rb
│       ├── system_test_helper.rb
│       └── trix_attachment.rb
└── actiontext.gemspec

Key abstractions

Constant	File	Purpose
ActionText::Attribute (has_rich_text)	actiontext/lib/action_text/attribute.rb	Macro added to AR models
ActionText::RichText	actiontext/app/models/action_text/rich_text.rb	The polymorphic AR model storing rich text
ActionText::Content	actiontext/lib/action_text/content.rb	Wrapper around a sanitized HTML fragment plus its attachments
ActionText::Attachment	actiontext/lib/action_text/attachment.rb	A <action-text-attachment> element
ActionText::Attachable	actiontext/lib/action_text/attachable.rb	Module included by anything that can be attached
ActionText::AttachmentGallery	actiontext/lib/action_text/attachment_gallery.rb	Multi-image inline gallery
ActionText::Engine	actiontext/lib/action_text/engine.rb	Mounts views and migration

How it works

class Message < ApplicationRecord
  has_rich_text :body
end

message.body = "<div>Hello <action-text-attachment sgid=\"...\">image.png</action-text-attachment></div>"

has_rich_text :body creates a polymorphic has_one :body, class_name: "ActionText::RichText" association. The HTML is sanitized on save (allowed tags configured in config.action_text.allowed_attachment_tags).

graph LR
    A[Form with trix-editor] --> B[Submitted HTML]
    B --> C[has_rich_text setter]
    C --> D[ActionText::Content sanitize]
    D --> E[ActionText::RichText AR record]
    E --> F[Render via partial]
    F --> G[Re-resolve sgid attachments]
    G --> H[Final HTML]

When the rich text is rendered, <action-text-attachment> elements are re-resolved: their sgid (signed global ID) maps to the attached record (typically an ActiveStorage::Blob), which is rendered via its own partial.

Attachables

ActionText::Attachable is included by anything that can appear inside rich text. The default attachable is an ActiveStorage::Blob. The attachables/ directory contains:

• content_attachment.rb — the <content> tag (used for galleries).
• missing_attachment.rb — graceful fallback when an attachment was deleted.
• remote_image.rb — external image URLs.

To make a custom model attachable:

class Photo < ApplicationRecord
  include ActionText::Attachable
end

It will then be referenceable from rich text via its signed GlobalID.

Editor

actiontext/app/javascript/actiontext/ contains the editor integration. Trix is the long-standing editor; Rails 8 work extends this with a ProseMirror-based alternative under lib/action_text/editor/.

actiontext/lib/action_text/trix_attachment.rb translates between Trix's serialized format and Action Text's <action-text-attachment> element.

Conversions

• html_conversion.rb — sanitize, render with attachments expanded.
• plain_text_conversion.rb — strip down to plain text (message.body.to_plain_text).
• markdown_conversion.rb — convert to Markdown.

Encryption

actiontext/lib/action_text/encryption.rb and app/models/action_text/encrypted_rich_text.rb add Active Record Encryption support so rich text bodies can be encrypted at rest.

Integration points

• Active Storage — embedded attachments are blobs.
• Active Record — has_rich_text is a model-level macro.
• Action View — partials in actiontext/app/views/action_text/ render rich text and attachments.

Entry points for modification

• Adding an attachable type: include ActionText::Attachable and provide a partial under app/views/<model_path>/_<model>.html.erb.
• Modifying sanitization rules: see ActionText::ContentHelper and actiontext/lib/action_text/content.rb.
• Adding an editor backend: extend actiontext/lib/action_text/editor/ and ship a JS bundle.

Related pages

• packages/active-storage — file storage for embedded attachments.
• packages/active-record — host records.
• packages/action-view — rendering pipeline for partials.