shrine 2.19.3 → 3.6.0

data/doc/carrierwave.md

@@ -1,16 +1,52 @@
-# Shrine for CarrierWave Users
+---
+title: Upgrading from CarrierWave
+---
 
 This guide is aimed at helping CarrierWave users transition to Shrine, and it
 consists of three parts:
 
 1. Explanation of the key differences in design between CarrierWave and Shrine
-2. Instructions how to migrate and existing app that uses CarrierWave to Shrine
+2. Instructions how to migrate an existing app that uses CarrierWave to Shrine
 3. Extensive reference of CarrierWave's interface with Shrine equivalents
 
-## Storage
+## Overview
 
-While in CarrierWave you configure storage in global configuration, in Shrine
-storage is a class which you can pass options to during initialization:
+### Uploader
+
+Shrine shares CarrierWave's concept of **uploaders**, classes which encapsulate
+file attachment logic for different file types:
+
+```rb
+class ImageUploader < Shrine
+  # attachment logic
+end
+```
+
+However, while CarrierWave uploaders are responsible for most of the
+attachment logic (uploading to temporary/permanent storage, retrieving the
+uploaded file, file validation, processing versions), Shrine distributes
+these responsibilities across several core classes:
+
+| Class                  | Description                                                        |
+| :----                  | :-----------                                                       |
+| `Shrine`               | handles uploads, metadata extraction, location generation          |
+| `Shrine::UploadedFile` | exposes metadata, implements downloading, URL generation, deletion |
+| `Shrine::Attacher`     | handles caching & storing, dirty tracking, persistence, versions   |
+
+Shrine uploaders themselves are functional: they receive a file on the input
+and return the uploaded file on the output. There are no state changes.
+
+```rb
+uploader      = ImageUploader.new(:store)
+uploaded_file = uploader.upload(file, :store)
+uploaded_file          #=> #<Shrine::UploadedFile>
+uploaded_file.url      #=> "https://my-bucket.s3.amazonaws.com/store/kfds0lg9rer.jpg"
+uploaded_file.download #=> #<File:/tmp/path/to/file>
+```
+
+### Storage
+
+In CarrierWave, you configure storage in global configuration:
 
 ```rb
 CarrierWave.configure do |config|
@@ -24,6 +60,9 @@ CarrierWave.configure do |config|
   config.fog_directory = "my-bucket"
 end
 ```
+
+In Shrine, the configuration options are passed directly to the storage class:
+
 ```rb
 Shrine.storages[:store] = Shrine::Storage::S3.new(
   bucket:            "my-bucket",
@@ -33,11 +72,11 @@ Shrine.storages[:store] = Shrine::Storage::S3.new(
 )
 ```
 
-In CarrierWave temporary storage cannot be configured; it saves and retrieves
-files from the filesystem, you can only set the directory. With Shrine both
-temporary (`:cache`) and permanent (`:store`) storage are first-class citizens
-and fully configurable, so you can also have files *cached* on S3 (preferrably
-via [direct uploads]):
+#### Temporary storage
+
+Where CarrierWave's temporary storage is hardcoded to disk, Shrine can use any
+storage for temporary storage. So, if you have multiple servers or want to do
+[direct uploads], you can use AWS S3 as temporary storage:
 
 ```rb
 Shrine.storages = {
@@ -46,97 +85,131 @@ Shrine.storages = {
 }
 ```
 
-## Uploader
+### Persistence
 
-Shrine shares CarrierWave's concept of *uploaders*, classes which encapsulate
-file attachment logic for different file types:
+While CarrierWave persists only the filename of the original uploaded file,
+Shrine persists storage and metadata information as well:
 
 ```rb
-class ImageUploader < Shrine
-  # attachment logic
-end
+{
+  "id": "path/to/image.jpg",
+  "storage": "store",
+  "metadata": {
+    "filename": "nature.jpg",
+    "size": 4739472,
+    "mime_type": "image/jpeg"
+  }
+}
 ```
 
-However, uploaders in CarrierWave are very broad; in addition to uploading and
-deleting files, they also represent the uploaded file. Shrine has a separate
-`Shrine::UploadedFile` class which represents the uploaded file.
+This way we have all information about uploaded files, without having to
+retrieve the file from the storage.
 
 ```rb
-uploaded_file = ImageUploader.upload(file, :store)
-uploaded_file          #=> #<Shrine::UploadedFile>
-uploaded_file.url      #=> "https://my-bucket.s3.amazonaws.com/store/kfds0lg9rer.jpg"
-uploaded_file.download #=> #<Tempfile>
+photo.image.id          #=> "path/to/image.jpg"
+photo.image.storage_key #=> :store
+photo.image.metadata    #=> { "filename" => "...", "size" => ..., "mime_type" => "..." }
+
+photo.image.original_filename #=> "nature.jpg"
+photo.image.size              #=> 4739472
+photo.image.mime_type         #=> "image/jpeg"
 ```
 
+#### Location
+
+CarrierWave persists only the filename of the uploaded file, and recalculates
+the full location dynamically based on location configuration. This can be
+dangerous, because if some component of the location happens to change, all
+existing links might become invalid.
+
+To avoid this, Shrine persists the full location on attachment, and uses it
+when generating file URL. So, even if you change how file locations are
+generated, existing files that are on old locations will still remain
+accessible.
+
 ### Processing
 
-In contrast to CarrierWave's class-level DSL, in Shrine processing is defined
-and performed on the instance-level. The result of processing can be a single
-file or a hash of versions:
+CarrierWave uses a class-level DSL for generating versions, which internally
+uses uploader subclassing and does in-place processing.
 
 ```rb
 class ImageUploader < CarrierWave::Uploader::Base
   include CarrierWave::MiniMagick
 
-  process resize_to_limit: [800, 800]
+  version :large do
+    process resize_to_limit: [800, 800]
+  end
 
   version :medium do
     process resize_to_limit: [500, 500]
   end
 
-  version :small, from_version: :medium do
+  version :small do
     process resize_to_limit: [300, 300]
   end
 end
 ```
 
+In contrast, in Shrine you perform processing on the instance level as a
+functional transformation, which is a lot simpler and more flexible:
+
 ```rb
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
-  plugin :processing
-  plugin :versions
-
-  process(:store) do |io, context|
-    versions = {}
+  plugin :derivatives
 
-    io.download do |original|
-      pipeline = ImageProcessing::MiniMagick.source(original)
+  Attacher.derivatives do |original|
+    magick = ImageProcessing::MiniMagick.source(original)
 
-      versions[:original]  = pipeline.resize_to_limit!(800, 800)
-      versions[:medium] = pipeline.resize_to_limit!(500, 500)
-      versions[:small]  = pipeline.resize_to_limit!(300, 300)
-    end
-
-    versions # return the hash of processed files
+    {
+      large:  magick.resize_to_limit!(800, 800),
+      medium: magick.resize_to_limit!(500, 500),
+      small:  magick.resize_to_limit!(300, 300),
+    }
   end
 end
 ```
 
-This allows you to fully optimize processing, because you can easily specify
-which files are processed from which, and even add parallelization.
+#### Retrieving versions
 
-CarrierWave performs processing before validations, which is a huge security
-issue, as it allows users to give arbitrary files to your processing tool, even
-if you have validations. Shrine performs processing after validations.
+When retrieving versions, CarrierWave returns a list of declared versions which
+may or may not have been generated. In contrast, Shrine persists data of
+uploaded processed files into the database (including any extracted metadata),
+which then becomes the source of truth on which versions have been generated.
+
+```rb
+photo.image              #=> #<Shrine::UploadedFile id="original.jpg" ...>
+photo.image_derivatives  #=> {}
+
+photo.image_derivatives! # triggers processing
+photo.image_derivatives  #=>
+# {
+#   large:  #<Shrine::UploadedFile id="large.jpg"  metadata={"size"=>873232, ...} ...>,
+#   medium: #<Shrine::UploadedFile id="medium.jpg" metadata={"size"=>94823,  ...} ...>,
+#   small:  #<Shrine::UploadedFile id="small.jpg"  metadata={"size"=>37322,  ...} ...>,
+# }
+```
 
 #### Reprocessing versions
 
 Shrine doesn't have a built-in way of regenerating versions, because that has
-to be written and optimized differently depending on whether you're adding or
-removing a version, what ORM are you using, how many records there are in the
-database etc. The [Reprocessing versions] guide provides some useful tips on
-this task.
+to be written and optimized differently depending on what versions have changed
+which persistence library you're using, how many records there are in the table
+etc.
+
+However, there is an extensive guide for [Managing Derivatives], which provides
+instructions on how to make these changes safely and with zero downtime.
 
-### Validations
+### Validation
 
-Like with processing, validations in Shrine are also defined and performed on
-instance-level:
+File validation in Shrine is also instance-level, which allows using
+conditionals:
 
 ```rb
 class ImageUploader < CarrierWave::Uploader::Base
   def extension_whitelist
-    %w[jpg jpeg gif png]
+    %w[jpg jpeg png webp]
   end
 
   def content_type_whitelist
@@ -154,107 +227,75 @@ class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_extension_inclusion %w[jpg jpeg gif png]
-    validate_mime_type_inclusion %w[image/jpeg image/gif image/png]
-    validate_max_size 10*1024*1024 unless record.admin?
+    validate_max_size 10*1024*1024
+    validate_extension %w[jpg jpeg png webp]
+
+    if validate_mime_type %w[image/jpeg image/png image/webp]
+      validate_max_dimensions [5000, 5000]
+    end
   end
 end
 ```
 
-## Attachments
+#### Custom metadata
 
-Like CarrierWave, Shrine also provides integrations with ORMs. It ships with
-plugins for both Sequel and ActiveRecord, but can also be used with just PORO
-models.
+With Shrine you can also extract and validate any custom metadata:
 
 ```rb
-Shrine.plugin :sequel       # if you're using Sequel
-Shrine.plugin :activerecord # if you're using ActiveRecord
-```
+class VideoUploader < Shrine
+  plugin :add_metadata
+  plugin :validation
 
-Instead of giving you class methods for "mounting" uploaders, in Shrine you
-generate attachment modules which you simply include in your models, which
-gives your models similar set of methods that CarrierWave gives:
+  add_metadata :duration do |io|
+    FFMPEG::Movie.new(io.path).duration
+  end
 
-```rb
-class Photo < ActiveRecord::Base
-  extend CarrierWave::ActiveRecord # done automatically by CarrierWave
-  mount_uploader :image, ImageUploader
-end
-```
-```rb
-class Photo < ActiveRecord::Base
-  include ImageUploader::Attachment.new(:avatar)
+  Attacher.validate do
+    if file.duration > 5*60*60
+      errors << "must not be longer than 5 hours"
+    end
+  end
 end
 ```
 
-### Attachment column
+### Multiple uploads
 
-You models are required to have the `<attachment>_data` column, which Shrine
-uses to save storage, location, and metadata of the uploaded file.
+Shrine doesn't have support for multiple uploads out-of-the-box like
+CarrierWave does. Instead, you can implement them using a separate table with a
+one-to-many relationship to which the files will be attached. The [Multiple
+Files] guide explains this setup in more detail.
 
-```rb
-photo.image_data #=>
-# {
-#   "storage" => "store",
-#   "id" => "photo/1/image/0d9o8dk42.png",
-#   "metadata" => {
-#     "filename"  => "nature.png",
-#     "size"      => 49349138,
-#     "mime_type" => "image/png"
-#   }
-# }
+## Migrating from CarrierWave
 
-photo.image.original_filename #=> "nature.png"
-photo.image.size              #=> 49349138
-photo.image.mime_type         #=> "image/png"
-```
+You have an existing app using CarrierWave and you want to transfer it to
+Shrine. Let's assume we have a `Photo` model with the "image" attachment.
 
-This is much more powerful than storing only the filename like CarrierWave
-does, as it allows you to also store any additional metadata that you might
-want to extract.
+### 1. Add Shrine column
 
-Unlike CarrierWave, Shrine will store this information for each processed
-version, making them first-class citizens:
+First we need to create the `image_data` column for Shrine:
 
 ```rb
-photo.image[:original]       #=> #<Shrine::UploadedFile>
-photo.image[:original].width #=> 800
-
-photo.image[:thumb]          #=> #<Shrine::UploadedFile>
-photo.image[:thumb].width    #=> 300
+add_column :photos, :image_data, :text # or :json or :jsonb if supported
 ```
 
-Also, since CarrierWave stores only the filename, it has to recalculate the
-full location each time it wants to generate the URL. That makes it really
-difficult to move files to a new location, because changing how the location is
-generated will now cause incorrect URLs to be generated for all existing files.
-Shrine calculates the whole location only once and saves it to the column.
-
-### Multiple uploads
+### 2. Dual write
 
-Shrine doesn't have support for multiple uploads like CarrierWave does, instead
-it expects that you will attach each file to a separate database record. This
-is a good thing, because the implementation is specific to the ORM you're
-using, and it's analogous to how you would implement any nested one-to-many
-associations. Take a look at the [demo app] which shows how easy it is to
-implement multiple uploads.
-
-## Migrating from CarrierWave
-
-You have an existing app using CarrierWave and you want to transfer it to
-Shrine. Let's assume we have a `Photo` model with the "image" attachment. First
-we need to create the `image_data` column for Shrine:
+Next, we need to make new CarrierWave attachments write to the
+`image_data` column. This can be done by including the below module to all
+models that have CarrierWave attachments:
 
 ```rb
-add_column :photos, :image_data, :text # or :json or :jsonb if supported
-```
+# config/initializers/shrine.rb (Rails)
+require "shrine"
+
+Shrine.storages = {
+  cache: ...,
+  store: ...,
+}
 
-Afterwards we need to make new uploads write to the `image_data` column. This
-can be done by including the below module to all models that have CarrierWave
-attachments:
+Shrine.plugin :model
+Shrine.plugin :derivatives
 
-```rb
 module CarrierwaveShrineSynchronization
   def self.included(model)
     model.before_save do
@@ -266,38 +307,36 @@ module CarrierwaveShrineSynchronization
 
   def write_shrine_data(name)
     uploader = send(name)
+    attacher = Shrine::Attacher.from_model(self, name)
 
     if read_attribute(name).present?
-      data = uploader_to_shrine_data(uploader)
+      attacher.set shrine_file(uploader)
 
-      if uploader.versions.any?
-        data = {original: data}
-        uploader.versions.each do |name, version|
-          data[name] = uploader_to_shrine_data(version)
-        end
+      uploader.versions.each do |version_name, version|
+        attacher.merge_derivatives(version_name => shrine_file(version))
       end
-
-      # Remove the `.to_json` if you're using a JSON column, otherwise the JSON
-      # object will be saved as an escaped string.
-      write_attribute(:"#{name}_data", data.to_json)
     else
-      write_attribute(:"#{name}_data", nil)
+      attacher.set nil
     end
   end
 
   private
 
-  # If you'll be using `:prefix` on your Shrine storage, make sure to
-  # subtract it from the path assigned as `:id`.
-  def uploader_to_shrine_data(uploader)
-    filename = read_attribute(uploader.mounted_as)
-    path     = uploader.store_path(filename)
+  def shrine_file(uploader)
+    name     = uploader.mounted_as
+    filename = read_attribute(name)
+    location = uploader.store_path(filename)
+    location = location.sub(%r{^#{storage.prefix}/}, "") if storage.prefix
+
+    Shrine.uploaded_file(
+      storage:  :store,
+      id:       location,
+      metadata: { "filename" => filename },
+    )
+  end
 
-    {
-      storage: :store,
-      id: path,
-      metadata: { filename: filename }
-    }
+  def storage
+    Shrine.storages[:store]
   end
 end
 ```
@@ -309,20 +348,27 @@ end
 ```
 
 After you deploy this code, the `image_data` column should now be successfully
-synchronized with new attachments.  Next step is to run a script which writes
-all existing CarrierWave attachments to `image_data`:
+synchronized with new attachments.
+
+### 3. Data migration
+
+Next step is to run a script which writes all existing CarrierWave attachments
+to `image_data`:
 
 ```rb
 Photo.find_each do |photo|
-  Photo.uploaders.each_key { |name| photo.write_shrine_data(name) }
+  photo.write_shrine_data(:image)
   photo.save!
 end
 ```
 
+### 4. Rewrite code
+
 Now you should be able to rewrite your application so that it uses Shrine
-instead of CarrierWave, using equivalent Shrine storages. For help with
-translating the code from CarrierWave to Shrine, you can consult the reference
-below.
+instead of CarrierWave (you can consult the reference in the next section). You
+can remove the `CarrierwaveShrineSynchronization` module as well.
+
+### 5. Backfill metadata
 
 You'll notice that Shrine metadata will be absent from the migrated files'
 data. You can run a script that will fill in any missing metadata defined in
@@ -332,11 +378,20 @@ your Shrine uploader:
 Shrine.plugin :refresh_metadata
 
 Photo.find_each do |photo|
-  attachment = ImageUploader.uploaded_file(photo.image, &:refresh_metadata!)
-  photo.update(image_data: attachment.to_json)
+  attacher = photo.image_attacher
+  attacher.refresh_metadata!
+  attacher.atomic_persist
 end
 ```
 
+### 6. Remove CarrierWave column
+
+If everything is looking good, we can remove the CarrierWave column:
+
+```rb
+remove_column :photos, :image
+```
+
 ## CarrierWave to Shrine direct mapping
 
 ### `CarrierWave::Uploader::Base`
@@ -358,26 +413,28 @@ end
 
 #### `.process`, `.version`
 
-As explained in the "Processing" section, processing is done by overriding the
-`Shrine#process` method.
-
-#### `.before`, `.after`
-
-In Shrine you can get callbacks by loading the `hooks` plugin. Unlike
-CarrierWave, and much like Sequel, Shrine implements callbacks by overriding
-instance methods:
+Processing is defined by using the `derivatives` plugin:
 
 ```rb
 class ImageUploader < Shrine
-  plugin :hooks
+  plugin :derivatives
+
+  Attacher.derivatives do |original|
+    magick = ImageProcessing::MiniMagick.source(image)
 
-  def after_upload(io, context)
-    super
-    # do something
+    {
+      large:  magick.resize_to_limit!(800, 800),
+      medium: magick.resize_to_limit!(500, 500),
+      small:  magick.resize_to_limit!(300, 300),
+    }
   end
 end
 ```
 
+#### `.before`, `.after`
+
+There is no Shrine equivalent for CarrierWave's callbacks.
+
 #### `#store!`, `#cache!`
 
 In Shrine you store and cache files by passing the corresponding storage to
@@ -406,8 +463,9 @@ uploaded_file.download #=> #<Tempfile:/path/to/file>
 In Shrine you call `#url` on uploaded files:
 
 ```rb
-user.avatar #=> #<Shrine::UploadedFile>
-user.avatar.url #=> "/uploads/398454ujedfggf.jpg"
+photo.image     #=> #<Shrine::UploadedFile>
+photo.image.url #=> "/uploads/398454ujedfggf.jpg"
+photo.image_url #=> "/uploads/398454ujedfggf.jpg" (shorthand)
 ```
 
 #### `#identifier`
@@ -415,26 +473,34 @@ user.avatar.url #=> "/uploads/398454ujedfggf.jpg"
 This method corresponds to `#original_filename` on the uploaded file:
 
 ```rb
-user.avatar #=> #<Shrine::UploadedFile>
-user.avatar.original_filename #=> "avatar.jpg"
+photo.image                   #=> #<Shrine::UploadedFile>
+photo.image.original_filename #=> "avatar.jpg"
 ```
 
 #### `#store_dir`, `#cache_dir`
 
-Shrine here provides a `#generate_location` method, which is triggered for all
-storages:
+Shrine here provides a single `#generate_location` method that's triggered for
+all storages:
 
 ```rb
 class ImageUploader < Shrine
-  def generate_location(io, context)
-    "#{context[:record].class}/#{context[:record].id}/#{io.original_filename}"
+  def generate_location(io, record: nil, name: nil, **)
+    [ storage_key,
+      record && record.class.name.underscore,
+      record && record.id,
+      super,
+      io.original_filename ].compact.join("/")
   end
 end
 ```
+```
+cache/user/123/2feff8c724e7ce17/nature.jpg
+store/user/456/7f99669fde1e01fc/kitten.jpg
+...
+```
 
-The `context` variable holds the additional data, like the attacment name and
-the record instance. You might also want to use the `pretty_location` plugin
-for automatically generating an organized folder structure.
+You might also want to use the `pretty_location` plugin for automatically
+generating an organized folder structure.
 
 #### `#default_url`
 
@@ -444,18 +510,15 @@ For default URLs you can use the `default_url` plugin:
 class ImageUploader < Shrine
   plugin :default_url
 
-  Attacher.default_url do |options|
-    "/attachments/#{name}/default.jpg"
+  Attacher.default_url do |derivative: nil, **|
+    "/fallbacks/#{derivative || "original"}.jpg"
   end
 end
 ```
 
-The `context` variable holds the name of the attachment, record instance and
-in some cases the `:version`.
-
 #### `#extension_white_list`, `#extension_black_list`
 
-In Shrine extension whitelisting/blacklisting is a part of validations, and is
+In Shrine, extension whitelisting/blacklisting is a part of validations, and is
 provided by the `validation_helpers` plugin:
 
 ```rb
@@ -469,9 +532,9 @@ class ImageUploader < Shrine
 end
 ```
 
-#### `#blacklist_mime_type_pattern`, `#whitelist_mime_type_pattern`, `#content_type_whitelist`, `#content_type_blacklist`
+####  `#content_type_whitelist`, `#content_type_blacklist`
 
-In Shrine MIME type whitelisting/blacklisting is part of validations, and is
+In Shrine, MIME type whitelisting/blacklisting is part of validations, and is
 provided by the `validation_helpers` plugin, though it doesn't support regexes:
 
 ```rb
@@ -485,19 +548,28 @@ class ImageUploader < Shrine
 end
 ```
 
+Make sure to also load the `determine_mime_type` plugin to detect MIME type
+from file content.
+
+```rb
+# Gemfile
+gem "mimemagic"
+```
+```rb
+Shrine.plugin :determine_mime_type, analyzer: :mimemagic
+```
+
 #### `#size_range`
 
 In Shrine file size validations are typically done using the
 `validation_helpers` plugin:
 
-
 ```rb
 class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_min_size 0
-    validate_max_size 5*1024*1024 # 5 MB
+    validate_size 0..5*1024*1024 # 5 MB
   end
 end
 ```
@@ -506,13 +578,13 @@ end
 
 Shrine doesn't have a built-in way of regenerating versions, because that's
 very individual and depends on what versions you want regenerated, what ORM are
-you using, how many records there are in your database etc. The [Regenerating
-versions] guide provides some useful tips on this task.
+you using, how many records there are in your database etc. The [Managing
+Derivatives] guide provides some useful tips on this task.
 
 ### Models
 
 The only thing that Shrine requires from your models is a `<attachment>_data`
-column (e.g. if your attachment is "avatar", you need the `avatar_data` column).
+column (e.g. if your attachment is "image", you need the `image_data` column).
 
 #### `.mount_uploader`
 
@@ -523,7 +595,7 @@ Shrine.plugin :sequel
 ```
 ```rb
 class User < Sequel::Model
-  include ImageUploader::Attachment.new(:avatar)
+  include ImageUploader::Attachment(:avatar)
 end
 ```
 
@@ -532,7 +604,7 @@ end
 The attachment module adds an attachment setter:
 
 ```rb
-user.avatar = File.open("avatar.jpg")
+photo.image = File.open("avatar.jpg", "rb")
 ```
 
 Note that unlike CarrierWave, you cannot pass in file paths, the input needs to
@@ -544,8 +616,8 @@ CarrierWave returns the uploader, but Shrine returns a `Shrine::UploadedFile`,
 a representation of the file uploaded to the storage:
 
 ```rb
-user.avatar #=> #<Shrine::UploadedFile>
-user.avatar.methods #=> [:url, :download, :read, :exists?, :delete, ...]
+photo.image #=> #<Shrine::UploadedFile>
+photo.image.methods #=> [:url, :download, :read, :exists?, :delete, ...]
 ```
 
 If attachment is missing, nil is returned.
@@ -556,13 +628,13 @@ This method is simply a shorthand for "if attachment is present, call `#url`
 on it, otherwise return nil":
 
 ```rb
-user.avatar_url #=> nil
-user.avatar = File.open("avatar.jpg")
-user.avatar_url #=> "/uploads/ksdf934rt.jpg"
+photo.image_url #=> nil
+photo.image = File.open("avatar.jpg", "rb")
+photo.image_url #=> "/uploads/ksdf934rt.jpg"
 ```
 
-The `versions` plugin extends this method to also accept a version name as the
-argument (`user.avatar_url(:thumb)`).
+The `derivatives` plugin extends this method to also accept a version name as
+the argument (`photo.image_url(:thumb)`).
 
 #### `#<attachment>_cache`
 
@@ -573,9 +645,9 @@ that you can use for retaining the cached file:
 Shrine.plugin :cached_attachment_data
 ```
 ```rb
-form_for @user do |f|
-  f.hidden_field :avatar, value: @user.cached_avatar_data
-  f.file_field :avatar
+form_for @photo do |f|
+  f.hidden_field :image, value: @photo.cached_image_data, id: nil
+  f.file_field :image
 end
 ```
 
@@ -594,7 +666,7 @@ shows what are Shrine's equivalents.
 
 #### `root`, `base_path`, `permissions`, `directory_permissions`
 
-In Shrine these are configured on the FileSystem storage directly.
+In Shrine these are configured on the `FileSystem` storage directly.
 
 #### `storage`, `storage_engines`
 
@@ -608,7 +680,7 @@ By default Shrine deletes cached and replaced files, but you can choose to keep
 those files by loading the `keep_files` plugin:
 
 ```rb
-Shrine.plugin :keep_files, cached: true, replaced: true
+Shrine.plugin :keep_files
 ```
 
 #### `move_to_cache`, `move_to_store`
@@ -632,8 +704,8 @@ class ImageUploader < Shrine
   Attacher.validate do
     # Evaluated inside an instance of Shrine::Attacher.
     if record.guest?
-      validate_max_size 2*1024*1024, message: "is too large (max is 2 MB)"
-      validate_mime_type_inclusion %w[image/jpg image/png image/gif]
+      validate_max_size 2*1024*1024, message: "must not be larger than 2 MB"
+      validate_mime_type %w[image/jpg image/png image/webp]
     end
   end
 end
@@ -661,9 +733,10 @@ multipart or not.
 
 ### `CarrierWave::Storage::Fog`
 
-You can use [`Shrine::Storage::S3`] \(built-in\),
-[`Shrine::Storage::GoogleCloudStorage`], or generic [`Shrine::Storage::Fog`]
-storage. The reference will assume you're using S3 storage.
+You can use [`Shrine::Storage::S3`][S3] (built-in),
+[`Shrine::Storage::GoogleCloudStorage`][shrine-gcs], or generic
+[`Shrine::Storage::Fog`][shrine-fog] storage. The reference will assume you're
+using S3 storage.
 
 #### `:fog_credentials`, `:fog_directory`
 
@@ -684,7 +757,7 @@ Shrine::Storage::S3.new(
 The object data can be configured via the `:upload_options` hash:
 
 ```rb
-Shrine::Storage::S3.new(upload_options: {content_disposition: "attachment"}, **options)
+Shrine::Storage::S3.new(upload_options: { content_disposition: "attachment" }, **options)
 ```
 
 #### `:fog_public`
@@ -692,16 +765,16 @@ Shrine::Storage::S3.new(upload_options: {content_disposition: "attachment"}, **o
 The object permissions can be configured with the `:acl` upload option:
 
 ```rb
-Shrine::Storage::S3.new(upload_options: {acl: "private"}, **options)
+Shrine::Storage::S3.new(upload_options: { acl: "private" }, **options)
 ```
 
 #### `:fog_authenticated_url_expiration`
 
 The `#url` method accepts the `:expires_in` option, you can set the default
-expiration with the `default_url_options` plugin:
+expiration with the `url_options` plugin:
 
 ```rb
-plugin :default_url_options, store: {expires_in: 600}
+plugin :url_options, store: { expires_in: 600 }
 ```
 
 #### `:fog_use_ssl_for_aws`, `:fog_aws_accelerate`
@@ -709,14 +782,12 @@ plugin :default_url_options, store: {expires_in: 600}
 Shrine allows you to override the S3 endpoint:
 
 ```rb
-Shrine::Storage::S3.new(endpoint: "https://s3-accelerate.amazonaws.com", **options)
+Shrine::Storage::S3.new(use_accelerate_endpoint: true, **options)
 ```
 
-[image_processing]: https://github.com/janko/image_processing
-[demo app]: https://github.com/shrinerb/shrine/tree/master/demo
-[Reprocessing versions]: /doc/regenerating_versions.md#readme
+[Managing Derivatives]: https://shrinerb.com/docs/changing-derivatives
+[direct uploads]: https://shrinerb.com/docs/getting-started#direct-uploads
+[S3]: https://shrinerb.com/docs/storage/s3
+[shrine-gcs]: https://github.com/renchap/shrine-google_cloud_storage
 [shrine-fog]: https://github.com/shrinerb/shrine-fog
-[direct uploads]: /doc/direct_s3.md#readme
-[`Shrine::Storage::S3`]: /doc/storage/s3.md#readme
-[`Shrine::Storage::GoogleCloudStorage`]: https://github.com/renchap/shrine-google_cloud_storage
-[`Shrine::Storage::Fog`]: https://github.com/shrinerb/shrine-fog
+[Multiple Files]: https://shrinerb.com/docs/multiple-files