Pageflow and the Rails engine for multimedia storytelling

A Rails engine, not a JavaScript library

Pageflow is described as multimedia storytelling for the web, built in cooperation with WDR, and the readme makes the shape of the thing clear in one line: Pageflow is a Rails engine which roughly consists of the following components.

Those components are a full MVC stack to manage and display Pageflow stories, user and permission management with support for isolated accounts and user collaboration, a client side application for live preview editing of stories, background jobs to process and encode images, audios and videos, and generators to quickly bootstrap a new Rails application.

So this is server-side software. A story is a set of records in your database, the editing interface is a Rails application, and the public story is a rendered page. The JavaScript in the repository is the front end, built with Rollup and Babel, and the package manifest shows it is a Yarn workspace with three packages, a main `package` directory and two under `entry_types/`, one for paged entries and one for scrolled entries.

That entry types structure is the clearest signal of what the tool is for. A paged entry is a story you move through page by page, and a scrolled entry is one that scrolls. Supporting both as first class types, with separate packages for each, is a distinction that only makes sense for narrative formats, and it is why the topic tags are multimedia-storytelling, scrollytelling and storytelling.

The instance is a full product rather than a library. It carries a `Gemfile`, a `pageflow.gemspec`, a `Rakefile`, `admins/` for the ActiveAdmin interface, `app/` for the Rails application, `db/` for migrations and seeds, `entry_types/` for the story types, `spec/` for the test suite and a `doc/` directory of guides. A plugin system sits on top, with a wiki page listing the plugins and a JavaScript API reference for the `pageflow` package.

The library choices are fixed, and that is the main constraint

Pageflow assumes a specific set of libraries, and the list is short enough to read as the shape of the stack it expects.

Devise handles authentication, CanCanCan handles authorization, ActiveAdmin provides the administration interface, Resque is the default for background jobs, FriendlyId produces pretty URLs, and Paperclip handles attachment handling. The editor is built with Backbone and Marionette, and the frontend with React and Redux.

The interesting choice is the editor stack. A React and Redux frontend for the public story is unremarkable. A Backbone and Marionette editor alongside it is a deliberate split, with two different application frameworks in one product, and that is a maintenance cost that a team inherits rather than chooses.

The runtime requirements are equally specific. Pageflow runs in environments with Ruby 3.4 or newer, Node 22 or newer, Rails 7.2 or newer and below 8.2, a Redis server for Resque, a database server supported by Active Record with MySQL tested, ImageMagick, libvips, and the Audio Waveform Image Generator.

Two of those are worth pausing on. ImageMagick and libvips together are the image processing stack, and libvips is a hard requirement rather than an optional extra. The Audio Waveform Image Generator is the one that surprises people, since it is the tool that draws the waveform picture used for audio entries, and it is a separate binary to install rather than a gem.

Then there are the cloud accounts. Accounts of Amazon Web Services have to be registered for S3 file storage and optionally Cloudfront content delivery, and Zencoder for video and audio encoding. There is no local encoding path described in the documentation, which means the tool assumes you will hand media processing to a service.

S3 in development, because Zencoder needs the files

One configuration decision is worth calling out because it surprises people during setup.

Pageflow stores files in S3 buckets also in development mode. The reason given is that otherwise there's no way to have Zencoder encode them. In other words, the local development environment is not self-contained, and a developer running the app locally needs AWS credentials and a Zencoder account.

The configuration path is otherwise conventional. The host application can utilize environment variables to configure the API keys for S3 and Zencoder, and the variables can be found in the generated Pageflow initializer. For available configuration options and examples, the documentation points to the inline docs in `config/initializers/pageflow.rb` in the generated Rails app.

There is one Rails setting that is easy to miss and produces a confusing failure. The documentation asks you to ensure you have defined default url options in your environment's files, and gives the example for a development environment in `config/environments/development.rb`:

config.action_mailer.default_url_options = {host: 'localhost:3000'}

In production, `:host` should be set to the actual host of your application. This is about mailers generating links, and if it is missing the failure appears in an email rather than in the page, which is a bad way to find out.

The documentation also points to a separate guide on setting up external services for the S3 and Zencoder details, and there is a page on updating from a prior version of the gem, with the versioning policy documented separately. The readme recommends depending on a specific minor version using the pessimistic version constraint operator, and adding the gem to the Gemfile as `gem 'pageflow', '~> X.Y.Z'` with X.Y.Z replaced by the current Pageflow version.

The install is a Rails app, a generator and three background processes

The installation is a Rails application, and the first command is the standard generator with the MySQL adapter:

$ rails new my_pageflow --database=mysql
$ cd my_pageflow

There is a warning attached to the naming. Do not name your application `pageflow` since it will cause conflicts which constant names created by Pageflow itself.

Then you put your MySQL credentials in `config/database.yml` and create the database with `rake db:create`, add the gem lines to the Gemfile, and run `bundle install`.

The Gemfile additions are the Pageflow gem plus the Resque stack, and the comment in the documentation notes that the install generator sets up Resque as the Active Job backend:

# Gemfile
gem 'pageflow', '~> X.Y.Z'

# The install generator sets up Resque as Active Job backend
gem 'resque', '~> 1.25'
gem 'resque-scheduler', '~> 4.10'
gem 'redis', '~> 3.0'
gem 'redis-namespace', '~> 1.5'

The generator is then run as `rails generate pageflow:install`. The documentation explains what it does: the generator will invoke Active Admin and Devise generators in turn and apply some configuration changes, and when asked to overwrite the `db/seeds.rb` file you should choose yes. You can also run the single steps of the `install` generator one by one if you want to understand the configuration choices, with a wiki page called The Install Generator in Detail for that.

After the generator comes `rake db:migrate` and then `rake db:seed`, which populates the database with some example data so things do not look too blank in development mode.

Running the application needs more than the Rails server. In addition to the Rails server, you need to start two Rake tasks for the background job processing, and these tasks are listed in a `Procfile` which is generated in the project root folder by the Pageflow installer. The documentation suggests considering the foreman gem to start all of these processes, including the Rails server, with a single command in a development environment. There is also a built-in Resque web server mounted at `/background_jobs`, which you use to inspect the state of background jobs and restart failed jobs, and that functionality is only available for admins.

A live preview editor, which is where the real work happens

The client side application for live preview editing of stories is the component that separates Pageflow from a static site generator with media support.

The distinction matters because storytelling formats are not documents. A scrollytelling story is a sequence of chapters, each with its own media, its own layout and its own transitions, and the author needs to see the result as they build it rather than after a full publish. A live preview editor is that feedback loop, and the mention of live preview rather than a plain preview is the point: the preview updates while the story is edited.

The user and permission management component sits beside it, with support for isolated accounts and user collaboration. That combination, an editor plus multi-user permissions, is what you need for a newsroom where several people work on different parts of a story. It is also what makes Pageflow a product rather than a template.

The plugin system is the extension mechanism, and there is a wiki page listing the plugins. The JavaScript API reference for the `pageflow` package is published separately, which suggests the front end is meant to be extended by code as well as by configuration.

The background jobs are the other half of the system, and they are where the media pipeline lives. Images, audios and videos are processed and encoded in the background rather than during a request, which is the only way a large video can be part of a page, and the Zencoder account is what performs the encoding.

The `entry_types/` directory deserves one more mention, because it is where the product's opinion about content is encoded. Rather than a generic page model, there are explicit types for paged and scrolled stories, with their own front end packages, and the `package/` directory holds the shared JavaScript.

Where a full Rails engine is the wrong size of tool

There are three situations where Pageflow is the wrong answer, and they are all about weight.

The first is a site that needs a handful of embedded videos. Pageflow brings Ruby, Rails, Redis, Resque, MySQL, ImageMagick, libvips, the Audio Waveform Image Generator, an S3 bucket and a Zencoder account, for content that a static site with a video tag would handle. The dependency list is not incidental to the product, it is the product, and there is no way to take the story model without the pipeline.

The second is a team that cannot use the cloud services. The requirement for S3 storage is not a preference, because Zencoder needs to fetch the file, and the encoding account is named in the requirements. If your data residency rules forbid storing media in S3, this tool does not work, and no amount of configuration changes that.

The third is a stack you do not control. The Rails constraint is explicit, with a supported range of 7.2 to 8.2, a Ruby floor of 3.4 and a Node floor of 22. The Rails range has a ceiling, so every Rails upgrade eventually lands on your desk as a decision about this engine.

There is also the operational surface, which is the thing to plan for. Beyond the Rails server you need two Rake tasks for background job processing, and a failure in the media pipeline shows up as a story with a missing or unencoded video rather than as a stack trace. The built-in Resque web interface at `/background_jobs` exists precisely because that failure mode is common, and it is admin-only.

The honest summary is that Pageflow is a good fit for an organisation that publishes narrative multimedia as a regular part of its work and already has the Rails and cloud infrastructure to support it. For everything else, it is a very large answer to a smaller question.

Editorial conclusion

Pageflow fits a team that already runs Rails and wants to publish scrollytelling stories with a visual editor, a media pipeline and a permissions model, and that is prepared to run Redis, Resque workers and a set of cloud accounts. It is the wrong choice for a site that only needs to embed a video, and the wrong choice if you cannot host S3 storage and a transcoding service. Before adopting, verify three things: the Ruby, Node, Rails and MySQL versions your environment can meet, since the stated requirements are Ruby 3.4 or newer, Node 22 or newer and Rails between 7.2 and 8.2, whether you can register the required Amazon Web Services and Zencoder accounts, since Zencoder is what encodes the audio and video, and how you will run the two background Rake tasks that the documentation says you need in addition to the Rails server. The code is MIT licensed, the repository publishes no GitHub releases, and the last push was on 2026-10-16.

Frequently asked questions

Official sources

1. codevise/pageflow on GitHub
2. Issues
3. License: MIT
4. Project website
5. README