# Markdown image uploads with EasyMDE and Active Storage

Markdown is an excellent choice to write rich content because it's portable, format-free and, generally, more efficient than the alternatives.

However, one of the issues that usually comes with the standard Markdown editors is image handling.

Most of them let us “import” images by pasting the URL into a markdown image tag, but that can get annoying over time.

In this tutorial, **we will build an image upload feature into the EasyMDE editor using Rails and Active Storage.**

Let's start:

## What is EasyMDE?
EasyMDE is an open-source JavaScript Markdown editor, a maintained fork of SimpleMDE built on CodeMirror. It wraps a regular `<textarea>`, adds a toolbar, a side-by-side preview, autosave, and hooks for image uploads, and keeps the textarea as the source of truth. That last part is why it fits Rails well: your form still submits the same field, and your controller and model don't change.

## What we will build
For this tutorial, we will build a simple blog with a textarea form that will be able to handle the blog's content.

To enhance this form, we will add an image upload feature using Easy MDE's built-in capabilities and a Stimulus controller to make [direct uploads with Active Storage](https://avohq.io/blog/rails-s3-direct-uploads) work and also show a way to have regular and more customizable uploads in case you want to.

The result should look something like this:

{{gumlet video_id="67217a510522bbba81cc05b8" width="850" height="662" /}}

We will be hooking into EasyMDE's image upload features to make this work.

## The Rails app
The first step is to create a Rails app with some sensible defaults:

```shell
rails new easymde-uploads --css=tailwind --database=postgresql -j esbuild
```

Then we run the Active Storage setup process and db migrations:

```shell
bin/rails db:setup
bin/rails active_storage:install
bin/rails db:migrate
```

After this, we create a scaffolded `Post` model, which we will use for this tutorial. We just need for it to have a `content` field:

```shell
bin/rails generate scaffold Post title excerpt content:text
```

When we run this, we now have routes, controller actions, and views that we can use to CRUD the `Post` resource, but we will be focusing exclusively on creating a new `Post`.

After some styling customization, we now should have a form with a `content` textarea:

![Form with textarea](/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MzU5LCJwdXIiOiJibG9iX2lkIn19--bf9b8885867a2d18f7c03298d0b2ff9c625d9388/initial-form.webp)

Then, we add EasyMDE. I'm using **ESBuild** and adding it with yarn, but you can add it using import maps if you prefer it.

```shell
yarn add easymde
```

After adding the EasyMDE editor, we can join this altogether by adding a Stimulus controller in charge of rendering the editor:

```javascript
// app/javascript/controllers/easy_mde_controller.js
import { Controller } from "@hotwired/stimulus";
import EasyMDE from "easymde";

export default class extends Controller {
  connect() {
    this.editor = new EasyMDE(this.element);
  }
}
```

```erb
<%= f.text_area :content, data: {controller: "easy-mde"} %>
```

Now, the textarea becomes an instance of the editor:

![Easy MDE editor rendered](/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MzYwLCJwdXIiOiJibG9iX2lkIn19--eba35f31e1ae0d53078e0eb2a211aab9b25ec39b/editor-rendered.webp)

So now we're ready to handle the uploads, let's go:

{{further_reading slug="github-flavored-markdown-commonmarker" /}}

## Configuring the editor
The defaults work, but most apps change a few options. They go in the same Stimulus controller:

```javascript
// app/javascript/controllers/easy_mde_controller.js
import { Controller } from "@hotwired/stimulus";
import EasyMDE from "easymde";

export default class extends Controller {
  static values = { autosaveKey: String };

  connect() {
    this.editor = new EasyMDE({
      element: this.element,
      forceSync: true,
      spellChecker: false,
      minHeight: "300px",
      status: ["lines", "words"],
      autosave: this.hasAutosaveKeyValue
        ? { enabled: true, uniqueId: this.autosaveKeyValue, delay: 1000 }
        : undefined,
    });
  }

  disconnect() {
    this.editor.toTextArea();
    this.editor = null;
  }
}
```

```erb
<%= f.text_area :content, data: {controller: "easy-mde", easy_mde_autosave_key_value: dom_id(@post)} %>
```

A few notes:

- `forceSync: true` copies the editor's content into the textarea on every change, so form submissions and validations see the current text.
- `autosave` needs a `uniqueId` per record, or two drafts overwrite each other in local storage. `dom_id` gives you one.
- `toTextArea()` in `disconnect()` removes the editor when Turbo navigates away. Without it, coming back to a cached page can render two editors on one textarea.
- The editor's styles ship with the package at `easymde/dist/easymde.min.css`, so import that file in your CSS entry point.

## Uploading images 
The EasyMDE editor is pretty configurable, and it actually comes with image uploading features out of the box that can be enabled by setting the `uploadImage` option to true.

After we do this, we can configure the following options:

- **imageUploadEndpoint:** we have to provide an endpoint that will receive the POST request containing the image. To make it work, we need to adhere to the following contract: if the upload was successful, the endpoint should return `{"data": {"filePath": "path-to-file"}}` otherwise, we need to return `{"error": "errorCode"}` where errorCode can be `noFileGiven` (HTTP 400 Bad Request), `typeNotAllowed` (HTTP 415 Unsupported Media Type), `fileTooLarge` (HTTP 413 Payload Too Large), or `importError`.
- **imageCSRFName:** the name used by our backend to identify the CSRF token. In our case, it's **authenticity_token**.
- **imageCSRFToken:** the actual token returned by Rails obtained from the DOM.
- **imageAccept:** a string containing a comma-separated list of the accepted MIME types: “image/jpeg image/jpg image/webp image/png”.
- **imageMaxSize:** the maximum allowed size for each uploaded image, expressed in bytes. By default, it's set to accept images up to 2 MB.
- **imageUploadFunction:** it receives a custom function we create to customize the upload behavior in case we need to. The function receives three arguments: **file** which is the file itself, and two callbacks, **onSuccess and onError** which we call whenever the uploads succeed or fail. Note: if we pass this function, the `imageMaxSize`, `imageUploadEndpoint` and `imageCSRFToken` are no longer used. The documentation also states that the `imageAccept` config is also not used, but it's still used to discriminate which files we can pick when using the picker.
- **previewImagesInEditor:** receives a boolean and determines if images are displayed when inserted into the editor. 

In case we want to customize things like the feedback text or error messages, we can do so with the `imageTexts` and `errorMessages` config options, which both accept objects.

{{info}}
Enjoying this article? You might enjoy Avo, the ultimate [Rails admin](https://avohq.io/rails-admin) and internal tooling gem for Ruby on Rails that can help you build better Rails apps faster.
{{/info}}

### Direct Uploads
To have our images directly uploaded to a cloud storage service, we need to use the `imageUploadFunction` and let ActiveStorage handle the upload process.

For the purposes of this tutorial, we will assume you have everything set to handle direct uploads. You can check our [S3 uploads with Active Storage](https://avohq.io/blog/s3-uploads-with-active-storage) guide if you are not sure how to do it.

First, we need to install Active Storage:

```shell
yarn add @rails/activestorage
```

Then, we set the controller to handle direct uploads. Luckily, ActiveStorage `DirectUpload` class handles most of the tasks for us:

```javascript
// app/javascript/controlles/easy_mde_controller.js
import { Controller } from "@hotwired/stimulus";
import EasyMDE from "easymde";
import { DirectUpload } from "@rails/activestorage";

export default class extends Controller {
  static values = { uploadUrl: String };

  connect() {
    this.editor = new EasyMDE({
      element: this.element,
      uploadImage: true,
      imageAccept: "image/png, image/jpeg, image/jpg, image/webp",
      previewImagesInEditor: true,
      imageUploadFunction: this._handleImageUpload.bind(this),
    });
  }

  disconnect() {
    this.editor = null;
    this.element.toTextArea();
  }

  _handleImageUpload(file, onSuccess, onError) {
    const upload = new DirectUpload(file, this.uploadUrl);
    upload.create((error, blob) => {
      if (error) return onError(error);
      const imageUrl = this._encodedImageUrl(blob);
      onSuccess(imageUrl);
    });
  }

  _encodedImageUrl(blob) {
    return `/rails/active_storage/blobs/redirect/${
      blob.signed_id
    }/${encodeURIComponent(blob.filename)}`;
  }

  get uploadUrl() {
    return this.uploadUrlValue;
  }
}
```

{{info}}
The `_handleImageUpload` and `_encodedImageUrl` methods start with an underscore as a convention because they're private methods: their existence shouldn't be a concern outside the scope of the controller.
{{/info}}

Here we create a custom `_handleImageUpload` method that creates an instance of the `DirectUpload` class, which has a `create` method that receives a callback that can either receive an `error` or a `blob` which represents the uploaded file.

If we have an error, we return the EasyMDE's `onError` method; otherwise, we create an encoded URL for the image, which is actually a redirect to the actual resource location on the cloud storage.

In order for the controller to work correctly, we have to provide the `uploadUrl` in the markup:

```erb
<%= f.textarea :content, data: {controller: "easy-mde", easy_mde_upload_url_value: rails_direct_uploads_url} %>
```

After adding this, direct image uploads should work, and after being uploaded, they should also be inserted as Markdown at the current cursor position in the editor.

Thankfully, Active Storage handles almost all the work for us, but you might want to customize the upload experience or do extra things when uploading images with EasyMDE; that's why we can also build a more customized upload experience.

Let's see how we can do that:

### Custom uploads 
We can add our upload logic for scenarios where direct uploads are not enough.

Maybe we want to authorize the uploads or persist them to the database to process them later.

To achieve this with EasyMDE we can use the library's upload logic by providing an `imageUploadEndpoint` with the parameters explained at the beginning of this section to make it work.

However, I prefer the upload flow explicitly defined in the controller because it's easier to debug.

The first thing we need to do is define a route that we will pass to the controller:

```ruby
# config/routes.rb
post "image_uploads", to: "image_uploads#create", as: :image_uploads
```

```javascript
// app/javascript/controllers/easy_mde_controller.js
import { Controller } from "@hotwired/stimulus";
import EasyMDE from "easymde";

export default class extends Controller {
  static values = { uploadUrl: String };

  connect() {
    this.editor = new EasyMDE({
      element: this.element,
      uploadImage: true,
      imageAccept: "image/png, image/jpeg, image/jpg, image/webp",
      previewImagesInEditor: true,
      imageUploadFunction: this._handleImageUpload.bind(this),
    });
  }

  disconnect() {
    this.editor = null;
    this.element.toTextArea();
  }

  _handleImageUpload(file, onSuccess, onError) {
    const formData = new FormData();
    formData.append("file", file);

    fetch(this.uploadUrlValue, {
      method: "POST",
      body: formData,
      headers: {
        "X-CSRF-Token": this.csrfToken,
        Accept: "application/json"
      }
    }).then((response) => response.json())
      .then((data) => {
        onSuccess(data.url);
      }).catch((error) => {
        onError(error);
      })
  }

  get csrfToken() {
    return document.querySelector('meta[name="csrf-token"]').content;
  }
}
```

Then, in our Rails controller:

```ruby
class ImageUploadsController < ApplicationController
  before_action :authenticate_user!
  
  def create
    if params[:file].blank?
      return render json: { error: "noFileGiven" }, status: :unprocessable_entity
    end

    if !valid_content_type?
      return render json: { error: "typeNotAllowed" }, status: :unprocessable_entity
    end

    if params[:file].size > 2.megabytes
      return render json: { error: "fileTooLarge" }, status: :unprocessable_entity
    end

    blob = ActiveStorage::Blob.create_and_upload!(
      io: params[:file],
      filename: params[:file].original_filename,
      content_type: params[:file].content_type,
    )

    if blob.persisted?
      render json: { url: rails_blob_url(blob) }
    else
      render json: { error: "importError" }, status: :unprocessable_entity
    end
  end

  private

  def image_upload_params
    params.permit(:file)
  end

  def valid_content_type?
    allowed_content_types = %w[image/jpeg image/jpg image/png image/webp]
    allowed_content_types.include?(params[:file].content_type)
  end
end
```

For this example, we're not doing anything particularly special, we're actually just making a POST request to our endpoint and handling the file upload using the `ActiveStorage::Blog.create_and_upload!` method.

In the controller, we added some basic validations that return the errors EasyMDE expects. Consider refactoring this because the controller clearly has too many responsibilities.

The URL we return is also a redirect to the actual resource, just like in the direct uploads example.

As you can see, as long as you return a URL or an error message, you can customize the flow as you see fit.

{{warning}}
Please note that we're not doing any checks against potentially malicious file content. If you'd like to ship this to production, you should consider adding that feature, especially if you intend to ship the editor to end-users.
{{/warning}}

## FAQ
### Is EasyMDE the same as SimpleMDE?
EasyMDE started as a fork of SimpleMDE when SimpleMDE stopped getting updates. The API is close, so most SimpleMDE examples work with small changes, but EasyMDE is the one still maintained and the one to install today.

### How do I get the Markdown out of EasyMDE?
Call `editor.value()` to read it and `editor.value("text")` to set it. In a Rails form you rarely need either: with `forceSync: true` the textarea always holds the current Markdown and submits with the form like any other field.

### How do I render the Markdown that EasyMDE saves?
EasyMDE only edits text. Render it on the server with a Markdown library such as Commonmarker, which supports GitHub-flavored Markdown. See [GitHub-flavored Markdown with Commonmarker](https://avohq.io/blog/github-flavored-markdown-commonmarker).

### Is there a Markdown editor built for Rails?
Marksmith is a GitHub-style Markdown editor for Rails that we maintain. See [adding shortcodes to Marksmith](https://avohq.io/blog/marksmith-shortcodes) for what it looks like in a real app.

## Summary
In this tutorial, we learned how to upload images using the EasyMDE Markdown editor and Active Storage.

First, we learned how to use the `DirectUpload` class defined by Active Storage to handle direct uploads to a cloud storage service.

Then, we also showed how to achieve the same result but uploading the files in the backend with the `ActiveStorage::Blob.create_and_upload!` method in case we want to add some customization to the flow.

We could make the upload feature more robust by adding [CDN support](https://avohq.io/blog/cdn-for-active-storage-uploads) to improve performance or handling edge potential edge cases.

I hope this tutorial can help you improve the Markdown writing flow in your application, allowing you or your users to write more effectively.
