diff --git a/docs/.vitepress/getFiles.js b/docs/.vitepress/getFiles.js
index d722bf9c..2075f43c 100644
--- a/docs/.vitepress/getFiles.js
+++ b/docs/.vitepress/getFiles.js
@@ -19,7 +19,14 @@ const getFiles = (directory, version) => {
     .filter(path => path !== 'index.md')
     .filter(path => path !== 'common')
     .filter(path => !path.includes('_common.md'))
-    .map((path) => ({text: humanize(path.replace('.md', '')), link: `/${version}/${directory}/${path.replace('.md', '.html')}`}))
+    .map((path) => {
+      let text = humanize(path.replace('.md', ''))
+      if (text === 'Easy mde') {
+        text = 'Easy MDE'
+      }
+      const link = `/${version}/${directory}/${path.replace('.md', '.html')}`
+      return {text, link}
+    })
 }
 
 export {getFiles}
diff --git a/docs/3.0/fields/easy_mde.md b/docs/3.0/fields/easy_mde.md
new file mode 100644
index 00000000..6c59663c
--- /dev/null
+++ b/docs/3.0/fields/easy_mde.md
@@ -0,0 +1,56 @@
+---
+version: '1.0'
+license: community
+---
+
+# EasyMDE
+
+:::info
+Before Avo 3.17 this field was called `markdown`. It was renamed to `easy_mde` so we can add our own implementation with `markdown`.
+:::
+
+<Image src="/assets/img/fields/easy_mde.jpg" width="906" height="421" alt="Trix field" />
+
+The `easy_mde` field renders a [EasyMDE Markdown Editor](https://github.com/Ionaru/easy-markdown-editor) and is associated with a text or textarea column in the database.
+`easy_mde` field converts text within the editor into raw Markdown text and stores it back in the database.
+
+```ruby
+field :description, as: :easy_mde
+```
+
+:::info
+The `easy_mde` field is hidden from the **Index** view.
+:::
+
+## Options
+
+<Option name="`always_show`">
+
+By default, the content of the `easy_mde` field is not visible on the `Show` view, instead, it's hidden under a `Show Content` link that, when clicked, displays the content. You can set `easy_mde` to always display the content by setting `always_show` to `true`.
+
+<!-- @include: ./../common/default_boolean_false.md-->
+</Option>
+
+<Option name="`height`">
+Sets the value of the editor
+
+#### Default
+
+`auto`
+
+#### Possible values
+
+`auto` or any number in pixels.
+</Option>
+
+<Option name="`spell_checker`">
+Toggles the editor's spell checker option.
+
+```ruby
+field :description, as: :easy_mde, spell_checker: true
+```
+
+<!-- @include: ./../common/default_boolean_false.md-->
+</Option>
+
+<!-- ## Enable spell checker -->
diff --git a/docs/3.0/fields/markdown.md b/docs/3.0/fields/markdown.md
index cd9eb127..6824832b 100644
--- a/docs/3.0/fields/markdown.md
+++ b/docs/3.0/fields/markdown.md
@@ -1,52 +1,90 @@
 ---
-version: '1.0'
+version: '3.17'
 license: community
 ---
 
 # Markdown
 
-<Image src="/assets/img/fields/markdown.jpg" width="906" height="421" alt="Trix field" />
+:::info
+In Avo 3.17 we renamed the `markdown` field `easy_mde` and introduced this custom one.
+:::
 
-The `Markdown` field renders a [EasyMDE Markdown Editor](https://github.com/Ionaru/easy-markdown-editor) and is associated with a text or textarea column in the database.
-`Markdown` field converts text within the editor into raw Markdown text and stores it back in the database.
+This field is inspired by the wonderful GitHub editor we all love and use.
 
-The Markdown field is hidden from the **Index** view.
+It supports applying styles to the markup and dropping files in the editor. The file will be taken over by Rails and persisted using Active Storage.
 
 
 ```ruby
-field :description, as: :markdown
+field :body, as: :markdown
 ```
 
-## Options
-
-<Option name="`always_show`">
-
-By default, the content of the `Markdown` field is not visible on the `Show` view, instead, it's hidden under a `Show Content` link that, when clicked, displays the content. You can set Markdown to always display the content by setting `always_show` to `true`.
+:::warning
+Please add the `redcarpet` gem to your `Gemfile`
+```ruby
+gem "redcarpet"
+```
+:::
 
-<!-- @include: ./../common/default_boolean_false.md-->
-</Option>
+## Customize the parser & renderer
 
-<Option name="`height`">
-Sets the value of the editor
+There are two places where we parse the markdown into the HTML you see.
 
-#### Default
+1. In the controller
+2. In the <Show /> field component
 
-`auto`
+You may customize the renderer by overriding the implementation.
 
+### Everywhere
 
-#### Possible values
+Both parsers inherit from the same parser from the field. So you can override in the field and it will be visible everywhere.
 
-`auto` or any number in pixels.
-</Option>
+```ruby
+# config/initializers/avo.rb
+
+module Avo
+  module Fields
+    class MarkdownField < BaseField
+      def self.parser
+      # update this to your liking
+        renderer = ::Redcarpet::Render::HTML.new(hard_wrap: true)
+        ::Redcarpet::Markdown.new(renderer, lax_spacing: true, fenced_code_blocks: true, hard_wrap: true)
+      end
+    end
+  end
+end
+```
 
-<Option name="`spell_checker`">
-Toggles the editor's spell checker option.
+### In the controller
 
 ```ruby
-field :description, as: :markdown, spell_checker: true
+module Avo
+  class MarkdownPreviewsController < ApplicationController
+    def create
+      # fetch the resource to get some information off of it
+      resource_class = Avo.resource_manager.get_resource_by_name(params[:resource_class])
+      # initialize it
+      resource = resource_class.new view: :edit
+      # run field detection
+      resource.detect_fields
+      # fetch the field
+      field = resource.get_field(params[:field_id])
+      # render the result
+      @result = field.parser.render(params[:body])
+    end
+  end
+end
 ```
 
-<!-- @include: ./../common/default_boolean_false.md-->
-</Option>
+### In the `ShowFieldComponent`
 
-<!-- ## Enable spell checker -->
+```ruby
+# app/components/avo/fields/markdown_field/show_component.rb
+
+class Avo::Fields::MarkdownField::ShowComponent < Avo::Fields::ShowComponent
+  def parsed_body
+    renderer = Redcarpet::Render::HTML.new(hard_wrap: true)
+    parser = Redcarpet::Markdown.new(renderer, lax_spacing: true, fenced_code_blocks: true, hard_wrap: true)
+    parser.render(@field.value)
+  end
+end
+```
diff --git a/docs/3.0/upgrade.md b/docs/3.0/upgrade.md
index b392fb80..98a0c6f8 100644
--- a/docs/3.0/upgrade.md
+++ b/docs/3.0/upgrade.md
@@ -3,6 +3,19 @@
 We'll update this page when we release new Avo 3 versions.
 
 If you're looking for the Avo 2 to Avo 3 upgrade guide, please visit [the dedicated page](./avo-2-avo-3-upgrade).
+
+## Upgrade from 3.16.1 to 3.16.2
+
+<Option name="markdown renamed to easy_mde">
+
+We added a new GitHub-inspired `markdown` field which supports ActiveStorage and gives us better control over the whole experience.
+
+This lead to us renaming the old `markdown` field to `easy_mde` and naming this new one `markdown`.
+If you'd like your app to work the same as before, rename all your `:markdown` field to `:easy_mde`.
+Otherwise leave them like that and enjoy the new field.
+
+</Option>
+
 ## Upgrade from 3.15.3 to 3.15.4
 
 The `config.cache_resource_filters` option is now **obsolete** and has been replaced with `config.persistence`. If you previously had:
diff --git a/docs/public/assets/img/fields/markdown.jpg b/docs/public/assets/img/fields/easy_mde.jpg
similarity index 100%
rename from docs/public/assets/img/fields/markdown.jpg
rename to docs/public/assets/img/fields/easy_mde.jpg