DOCSEARCHbyAlgolia
Submit Docs

Marksmith Documentation

repository·main·Indexed 19 days ago

https://github.com/avo-hq/marksmith

A GitHub-style markdown editor for Ruby on Rails applications. Marksmith provides a rich editing experience with built-in preview rendering, Active Storage support for file uploads, and StimulusJS integration. It includes helpers for Rails forms, support for multiple markdown parsers (commonmarker, redcarpet, kramdown), and specialized integration as a plugin for Avo with dedicated markdown field types.

Tokens
2.9K
Snippets
13
Records
14
Agent score
68%

What's inside Marksmith

  1. Customize the Markdown renderer

    main

    Marksmith uses commonmarker by default, but you can switch to redcarpet or kramdown in your initializer.

    Configure Redcarpet options

    If using redcarpet, you can pass specific flags via redcarpet_options.

    Implement a custom renderer

    You can completely override the rendering logic by defining your own Marksmith::Renderer class.

    # config/initializers/marksmith.rb
Marksmith.configure do |config|
  config.parser = "redcarpet"
  config.redcarpet_options = {
    underline: false,
    highlight: false
  }
end
    # app/models/marksmith/renderer.rb
module Marksmith
  class Renderer
    def initialize(body:)
      @body = body
    end

    def render
      # Your custom renderer logic here
    end
  end
end

  2. Enable Dark Mode for Marksmith

    main

    Marksmith supports dark mode using a .dark class on a wrapper element. You can apply this class to a div, the form_with block, or the html tag.

    <%# Option 1: Wrapper element %>
<div class="dark">
  <%= marksmith_tag :body %>
</div>

<%# Option 2: Form class %>
<%= form_with model: post, class: "dark" do |form|
  <%= form.marksmith :body %>
<% end %>

<%# Option 3: HTML tag %>
<html class="dark">
  <%= marksmith_tag :body %>
</html>

  3. Install Marksmith in a Rails app

    main

    Marksmith requires Stimulus and Turbo to be configured in your Rails app. Follow these steps to install:

    1. Add the gems: Add marksmith and a markdown parser (like commonmarker) to your Gemfile.
    2. Install the NPM package: Install @avo-hq/marksmith via yarn or pin it using importmap.
    3. Register Stimulus controllers: Import and register MarksmithController in your application. Optionally register ListContinuationController for continued lists.
    4. Add stylesheets: Include the Marksmith stylesheet in your application layout.

    If you want to avoid bundling all dependencies and manage them manually, you can import from @avo-hq/marksmith/core instead.

    # Gemfile
gem "marksmith"
gem "commonmarker"
    # Install NPM package
yarn add @avo-hq/marksmith
# OR
bin/importmap pin @avo-hq/marksmith
    // Register controllers
import { MarksmithController, ListContinuationController } from '@avo-hq/marksmith'

application.register('marksmith', MarksmithController)
application.register('list-continuation', ListContinuationController)
    <%# application.html.erb %>
<%= stylesheet_link_tag "marksmith" %>

  4. Enable Media Library in MarkdownField

    main

    The MarkdownField can optionally use the Avo Media Library for asset management. This is controlled by the media_library option. The field will only attempt to use the media library if Avo::MediaLibrary.configuration.enabled is true and the field's @media_library attribute is truthy.

    # To explicitly enable media library (default behavior)
field :description, Marksmith::Fields::MarkdownField, media_library: true

# To disable media library integration
field :description, Marksmith::Fields::MarkdownField, media_library: false

  5. Configure Marksmith engine and mount path

    main

    You can customize the Marksmith engine behavior by ejecting the configuration file using bin/rails generate marksmith:install. This creates config/initializers/marksmith.rb.

    Change the mount path

    By default, the engine is mounted at /marksmith. You can change this via config.mount_path.

    Manual engine mounting

    If you want to disable automatic mounting, set config.automatically_mount_engine = false and mount it manually in config/routes.rb.

    # config/initializers/marksmith.rb
Marksmith.configure do |config|
  config.mount_path = "/markdown"
  # config.automatically_mount_engine = false
end
    # config/routes.rb
Rails.application.routes.draw do
  mount Marksmith::Engine => Marksmith.configuration.mount_path
end

  6. Integrate Marksmith with Avo

    main

    If you are using Avo, Marksmith can be registered as a plugin to provide specialized markdown fields. When Avo is defined, Marksmith registers the following field types:

    • :markdown
    • :marksmith

    It also automatically registers necessary Stimulus controllers (marksmith and list-continuation) and assets with the Avo asset manager.

  8. Use Marksmith in Rails forms

    main

    You can use Marksmith in your views using either a standalone tag or by attaching it to a form builder. The content is stored in your database as plain text.

    <%# Using the standalone tag %>
<%= marksmith_tag :body, value: "### This is important" %>

<%# Using the form builder %>
<%= form.marksmith :body %>

  9. Configure Marksmith field options

    main

    The marksmith_tag helper supports standard Rails form options (disabled, placeholder, autofocus, style, class, data, value) as well as custom Marksmith options:

    • extra_preview_params: A hash of parameters to send to the preview renderer.
    • enable_file_uploads: Boolean to enable/disable file uploads.
    • upload_url: The URL used for file uploads. If nil or not provided, it defaults to the rails_direct_uploads_url helper.
    <%= marksmith_tag :body,
  disabled: true,
  placeholder: "Write your best markdown here.",
  extra_preview_params: { foo: "bar" },
  enable_file_uploads: true,
  upload_url: nil
  %>

  10. Render markdown content with marksmithed

    main

    To render the compiled HTML from a markdown field in your views, use the marksmithed helper.

    Warning: Use <%== to output the raw HTML. You MUST sanitize the content to prevent XSS attacks.

    <%# In your show.html.erb %>
<%== marksmithed post.body %>

<%# Recommended: Sanitize the output %>
<%== sanitize(marksmithed(post.body), tags: %w(table th tr td span) + ActionView::Helpers::SanitizeHelper.sanitizer.vendor.safe_list_sanitizer.allowed_tags.to_a) %>

  11. Configure Redcarpet parser options

    main

    When using the redcarpet parser, you can pass specific options to customize its behavior. These options are applied via redcarpet_options within the Marksmith.configure block.

    Supported Redcarpet options:

    • tables: Enable tables (default: true)
    • lax_spacing: Enable lax spacing (default: true)
    • fenced_code_blocks: Enable fenced code blocks (default: true)
    • space_after_headers: Enable space after headers (default: true)
    • hard_wrap: Enable hard wrap (default: true)
    • autolink: Enable autolink (default: true)
    • strikethrough: Enable strikethrough (default: true)
    • underline: Enable underline (default: true)
    • highlight: Enable highlight (default: true)
    • quote: Enable quote (default: true)
    • with_toc_data: Enable TOC data (default: true)
    Marksmith.configure do |config|
  config.redcarpet_options = {
    tables: false,
    highlight: true
  }
end

  12. Configure the MarkdownField in Avo

    main

    The Marksmith::Fields::MarkdownField is used to integrate markdown editing capabilities into Avo interfaces. It inherits from Avo::Fields::BaseField and includes specific options for media library integration and preview parameters.

    Configuration Options

    OptionTypeDescription
    media_libraryBooleanEnables or disables the integration with the Avo Media Library. Defaults to true.
    extra_preview_paramsHashAdditional parameters passed to the markdown previewer.
    file_uploadsAnyConfiguration for handling file uploads within the markdown editor.

    Note: The MarkdownField is configured to hide_on :index by default, meaning it will not appear in index views.

    # Example usage in an Avo Resource
field :content, Marksmith::Fields::MarkdownField, 
      media_library: true, 
      extra_preview_params: { some_key: 'some_value' }