Markdown

The Markdown field provides a GitHub-inspired editor based on Marksmith, with text formatting, file attachments, and a preview of the rendered content.

# app/avo/resources/post.rb
field :body, as: :markdown

By default, the field is hidden on Index. The editor offers uploads when an upload URL is available and a gallery picker when the Media Library is enabled. Preview requests include Avo's resource and field identifiers, with no additional custom parameters.

INFO

In Avo 3.17 we renamed the previous markdown field easy_mde and introduced this one based on the Marksmith editor.

See the Marksmith repository for its editor configuration and renderer documentation.

Install the editor dependencies

WARNING

Ensure these gems are in your Gemfile.

# Gemfile
gem "marksmith"
gem "commonmarker"

Write and preview Markdown

Use the editor toolbar to format text, or write Markdown directly and switch to the preview panel to see the result. The editor supports:

• ActiveStorage file attachments
• Media Library integration
• Preview panel
• Ready-to-use renderer
• Text formatting
• Lists
• Links
• Images
• Tables
• Code blocks
• Headings

Control file attachments

Users can drop files into the editor or select them through the upload control. Rails persists uploaded files using Active Storage. The Media Library lets users reuse existing uploads.

To hide the "Upload files" option for a field, set file_uploads to false. Uploads otherwise depend on an available upload URL, normally through Active Storage.

# app/avo/resources/post.rb
field :body, as: :markdown, file_uploads: false

To hide "Attach from gallery" for a field while keeping the Media Library available elsewhere, set media_library to false.

# app/avo/resources/post.rb
field :body, as: :markdown, media_library: false

Pass context to the preview renderer

If the preview renderer needs additional context, pass key-value pairs through extra_preview_params. See the reference for the identifiers Avo already sends and how custom keys take precedence.

# app/avo/resources/post.rb
field :body, as: :markdown, extra_preview_params: { foo: :bar }

Customize the renderer

To change how Markdown becomes HTML in the preview and on the Show view, override Marksmith::Renderer. The following example supports Commonmarker, Kramdown, and Redcarpet; install the parser gems you use.

# app/models/marksmith/renderer.rb

module Marksmith
  class Renderer
    def initialize(body:)
      @body = body
    end

    def render
      if Marksmith.configuration.parser == "commonmarker"
        render_commonmarker
      elsif Marksmith.configuration.parser == "kramdown"
        render_kramdown
      else
        render_redcarpet
      end
    end

    def render_commonmarker
      # commonmarker expects an utf-8 encoded string
      body = @body.to_s.dup.force_encoding("utf-8")
      Commonmarker.to_html(body)
    end

    def render_redcarpet
      ::Redcarpet::Markdown.new(
        ::Redcarpet::Render::HTML,
        tables: true,
        lax_spacing: true,
        fenced_code_blocks: true,
        space_after_headers: true,
        hard_wrap: true,
        autolink: true,
        strikethrough: true,
        underline: true,
        highlight: true,
        quote: true,
        with_toc_data: true
      ).render(@body)
    end

    def render_kramdown
      body = @body.to_s.dup.force_encoding("utf-8")
      Kramdown::Document.new(body).to_html
    end
  end
end

Show the full content on the Show view

Set always_show to true to display the full content instead of a collapsed preview.

# app/avo/resources/post.rb
field :body, as: :markdown, always_show: true

INFO

The collapsed preview requires marksmith 0.6.0 or newer. On older versions the field always shows its full content and always_show has no effect.

See Field options for configuration shared with other field types.