### Install Marksmith NPM Package

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Install the Marksmith NPM package using yarn.

```bash
$ yarn add @avo-hq/marksmith
```

--------------------------------

### Install Marksmith NPM Package

Source: https://context7.com/avo-hq/marksmith/llms.txt

Install the Marksmith NPM package using Yarn or pin it using importmap for use with Stimulus controllers.

```bash
yarn add @avo-hq/marksmith

# Or with importmap
bin/importmap pin @avo-hq/marksmith
```

--------------------------------

### Generate Marksmith Install Configuration

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Generate the Marksmith initializer configuration file for your Rails application.

```bash
bin/rails generate marksmith:install
```

--------------------------------

### Marksmith Integration with form_for

Source: https://context7.com/avo-hq/marksmith/llms.txt

Integrate Marksmith into a `form_for` builder using the `f.marksmith` method. This example shows how to enable file uploads and pass extra parameters for previewing markdown content.

```erb
<!-- With form_for -->
<%= form_for @article do |f| %>
  <%= f.marksmith :content,
    enable_file_uploads: true,
    extra_preview_params: { article_type: @article.type }
  %>
  <%= f.submit %>
<% end %>
```

--------------------------------

### Register Marksmith Stimulus Controllers

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Import and register the MarksmithController and optionally the ListContinuationController in your application's Stimulus setup.

```javascript
import { MarksmithController, ListContinuationController } from '@avo-hq/marksmith'

application.register('marksmith', MarksmithController)
application.register('list-continuation', ListContinuationController)
```

--------------------------------

### Sanitize Markdown Content

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Example of sanitizing Markdown content to prevent XSS attacks, allowing specific HTML tags.

```ruby
sanitize(body, tags: %w(table th tr td span) + ActionView::Helpers::SanitizeHelper.sanitizer_vendor.safe_list_sanitizer.allowed_tags.to_a)
```

--------------------------------

### Add Marksmith Gem and Parser

Source: https://context7.com/avo-hq/marksmith/llms.txt

Install the Marksmith gem and a markdown parser like Commonmarker, Redcarpet, or Kramdown in your Rails application's Gemfile.

```ruby
gem "marksmith"
gem "commonmarker" # or "redcarpet" or "kramdown"
```

--------------------------------

### Configuring Active Storage for File Uploads

Source: https://context7.com/avo-hq/marksmith/llms.txt

Configure storage services and environment settings to enable file uploads.

```ruby
# Ensure Active Storage is configured
# config/storage.yml
local:
  service: Disk
  root: <%= Rails.root.join("storage") %>

# config/environments/development.rb
config.active_storage.service = :local
```

--------------------------------

### Importing Core Controllers Manually

Source: https://context7.com/avo-hq/marksmith/llms.txt

Use this approach to manage dependencies manually without bundled dependencies.

```javascript
// Import dependencies manually
import '@github/markdown-toolbar-element'
import { DirectUpload } from '@rails/activestorage'
import { post } from '@rails/request.js'
import { subscribe } from '@github/paste-markdown'

// Import just the core controllers
import { MarksmithController, ListContinuationController } from '@avo-hq/marksmith/core'

application.register('marksmith', MarksmithController)
application.register('list-continuation', ListContinuationController)
```

--------------------------------

### Enabling File Uploads via Helpers

Source: https://context7.com/avo-hq/marksmith/llms.txt

Use the marksmith_tag helper to toggle file upload capabilities.

```erb
<!-- Enable file uploads in the editor -->
<%= marksmith_tag :body, enable_file_uploads: true %>

<!-- Custom upload URL -->
<%= marksmith_tag :body,
  enable_file_uploads: true,
  upload_url: "/custom/uploads"
%>

<!-- Disable file uploads -->
<%= marksmith_tag :body, enable_file_uploads: false %>
```

--------------------------------

### Configure Marksmith Mount Path

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Set the mount path for the Marksmith engine in the initializer file.

```ruby
# config/initializers/marksmith.rb
Marksmith.configure do |config|
  config.mount_path = "/markdown"
end
```

--------------------------------

### Pin Marksmith NPM Package with Importmap

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Pin the Marksmith NPM package using importmap.

```bash
bin/importmap pin @avo-hq/marksmith
```

--------------------------------

### POST /marksmith/markdown_previews

Source: https://context7.com/avo-hq/marksmith/llms.txt

Renders markdown content into HTML, typically used for live preview functionality in the editor.

```APIDOC
## POST /marksmith/markdown_previews

### Description
This endpoint accepts markdown content and returns rendered HTML, often as a Turbo Stream response, to update a preview pane.

### Method
POST

### Endpoint
/marksmith/markdown_previews

### Request Body
- **body** (string) - Required - The markdown content to be rendered.
- **element_id** (string) - Optional - The ID of the DOM element to be updated.

### Request Example
{
  "body": "# Hello World\n\nThis is **bold** and *italic* text.",
  "element_id": "preview-pane-123"
}

### Response
#### Success Response (200)
- **Content** (text/vnd.turbo-stream.html) - The rendered HTML wrapped in a Turbo Stream response.
```

--------------------------------

### Configure Marksmith Initializer

Source: https://context7.com/avo-hq/marksmith/llms.txt

Customize Marksmith's behavior by modifying the initializer file. Options include changing the engine mount path, selecting a markdown parser, and controlling automatic engine mounting.

```ruby
# config/initializers/marksmith.rb
Marksmith.configure do |config|
  # Change the engine mount path (default: "/marksmith")
  config.mount_path = "/markdown"

  # Choose the markdown parser: "commonmarker", "redcarpet", or "kramdown"
  config.parser = "commonmarker"

  # Disable automatic engine mounting if you want to mount manually
  config.automatically_mount_engine = false
end
```

--------------------------------

### Manually Import Marksmith Controller

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Import only the MarksmithController and its dependencies manually if you need finer control over imports.

```javascript
// Manually import Marksmith's dependencies
import '@github/markdown-toolbar-element'
import { DirectUpload } from '@rails/activestorage'
import { post } from '@rails/request.js'
import { subscribe } from '@github/paste-markdown'

// Import just the controller
import { MarksmithController } from '@avo-hq/marksmith/core'

application.register('marksmith', MarksmithController)
```

--------------------------------

### Implement Custom Renderer

Source: https://context7.com/avo-hq/marksmith/llms.txt

Override the default rendering behavior by creating a Marksmith::Renderer class, useful for adding features like syntax highlighting.

```ruby
# app/models/marksmith/renderer.rb
module Marksmith
  class Renderer
    def initialize(body:)
      @body = body
    end

    def render
      # Custom rendering with syntax highlighting
      html = Commonmarker.to_html(@body.to_s.force_encoding("utf-8"))

      # Add syntax highlighting with Rouge
      doc = Nokogiri::HTML.fragment(html)
      doc.css('pre code').each do |code_block|
        language = code_block['class']&.gsub('language-', '') || 'text'
        formatter = Rouge::Formatters::HTML.new
        lexer = Rouge::Lexer.find_fancy(language, @body) || Rouge::Lexers::PlainText
        highlighted = formatter.format(lexer.lex(code_block.text))
        code_block.inner_html = highlighted
      end

      doc.to_html
    end
  end
end
```

--------------------------------

### Markdown Preview API

Source: https://context7.com/avo-hq/marksmith/llms.txt

Expose a preview endpoint for rendering markdown. Can be called via controller logic or manual HTTP requests.

```ruby
# The engine mounts this route automatically:
# POST /marksmith/markdown_previews

# Controller implementation
module Marksmith
  class MarkdownPreviewsController < ApplicationController
    def create
      @body = Marksmith::Renderer.new(body: params[:body]).render
    end
  end
end
```

```bash
# cURL example for manual preview rendering
curl -X POST "http://localhost:3000/marksmith/markdown_previews" \
  -H "Content-Type: application/json" \
  -H "Accept: text/vnd.turbo-stream.html" \
  -d '{
    "body": "# Hello World\n\nThis is **bold** and *italic* text.",
    "element_id": "preview-pane-123"
  }'

# Response: Turbo Stream HTML that updates the preview pane
```

--------------------------------

### Marksmith Form Helper and Form Builder Usage

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Demonstrates using the marksmith_tag helper and the form builder method to integrate the editor.

```erb
<%= marksmith_tag :body, value: "### This is important" %>
or
<%= form.marksmith :body %>
```

--------------------------------

### Configure Marksmith Parser

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Configure Marksmith to use a different Markdown parser like 'redcarpet' in an initializer file.

```ruby
# config/initializers/marksmith.rb
Marksmith.configure do |config|
  config.parser = "redcarpet"
end
```

--------------------------------

### Configure Stimulus Controller

Source: https://context7.com/avo-hq/marksmith/llms.txt

Define configuration values and targets for the Marksmith Stimulus controller via HTML data attributes and JavaScript class definitions.

```html
<!-- Full controller configuration -->
<div data-controller="marksmith list-continuation"
     data-marksmith-attach-url-value="/rails/active_storage/direct_uploads"
     data-marksmith-preview-url-value="/marksmith/markdown_previews"
     data-marksmith-extra-preview-params-value='{"context":"blog"}'
     data-marksmith-field-id-value="post_body"
     data-marksmith-gallery-enabled-value="true"
     data-marksmith-gallery-open-path-value="/media_library"
     data-marksmith-file-uploads-enabled-value="true"
     data-action="
       beforeinput->list-continuation#handleBeforeInput
       input->list-continuation#handleInput
     ">
  <!-- Editor content -->
</div>
```

```javascript
// Controller value definitions
export default class extends Controller {
  static values = {
    attachUrl: String,           // URL for file uploads (Active Storage)
    previewUrl: String,          // URL for markdown preview endpoint
    extraPreviewParams: Object,  // Additional params sent with preview requests
    fieldId: String,             // Unique identifier for the field
    galleryEnabled: Boolean,     // Enable media gallery integration
    galleryOpenPath: String,     // Path to open media gallery
    fileUploadsEnabled: Boolean, // Enable/disable file uploads
  }

  static targets = [
    'fieldContainer',    // Container for the textarea
    'fieldElement',      // The textarea element
    'previewPane',       // Preview rendering area
    'writeTabButton',    // Write tab button
    'previewTabButton',  // Preview tab button
    'toolbar'            // Toolbar container
  ]
}
```

--------------------------------

### Marksmith Tag with All Options

Source: https://context7.com/avo-hq/marksmith/llms.txt

Configure the `marksmith_tag` helper with various options including placeholder text, disabled state, autofocus, custom styling, file upload settings, and data attributes.

```erb
<!-- With all options -->
<%= marksmith_tag :body,
  value: "Initial content here",
  placeholder: "Write your markdown here...",
  disabled: false,
  autofocus: true,
  style: "min-height: 300px;",
  class: "my-custom-class",
  enable_file_uploads: true,
  upload_url: "/custom/upload/endpoint",
  extra_preview_params: { context: "blog_post", highlight_code: true },
  data: { custom_attribute: "value" }
%>
```

--------------------------------

### Automatic Upload Handling

Source: https://context7.com/avo-hq/marksmith/llms.txt

The controller automatically processes uploads and inserts markdown links.

```javascript
// The controller handles uploads automatically
// Drag and drop or paste images to upload
// Uploaded files are inserted as markdown links:
// ![filename.png](/rails/active_storage/blobs/redirect/signed_id/filename.png)
// [document.pdf](/rails/active_storage/blobs/redirect/signed_id/document.pdf)
```

--------------------------------

### Implementing Dark Mode

Source: https://context7.com/avo-hq/marksmith/llms.txt

Apply the dark class to parent elements or toggle via JavaScript to enable dark mode.

```erb
<!-- Dark mode on html element -->
<html class="dark">
  <body>
    <%= marksmith_tag :body %>
  </body>
</html>

<!-- Dark mode on wrapper -->
<div class="dark">
  <%= marksmith_tag :body %>
</div>

<!-- Dark mode with form -->
<%= form_with model: @post, class: "dark" do |form| %>
  <%= form.marksmith :body %>
  <%= form.submit %>
<% end %>

<!-- Toggle dark mode with JavaScript -->
<script>
  function toggleDarkMode() {
    document.documentElement.classList.toggle('dark');
  }
</script>
<button onclick="toggleDarkMode()">Toggle Dark Mode</button>
```

--------------------------------

### Add Marksmith Gem

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Add the marksmith gem and a markdown parser like commonmarker to your Gemfile using Bundler.

```bash
bundle add marksmith commonmarker
```

--------------------------------

### Include Marksmith Stylesheet

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Add the stylesheet link tag for Marksmith to your main application layout file.

```erb
<%= stylesheet_link_tag "marksmith" %>
```

--------------------------------

### Manually Mount Marksmith Engine

Source: https://context7.com/avo-hq/marksmith/llms.txt

If automatic engine mounting is disabled, manually mount the Marksmith engine in your `config/routes.rb` file, specifying the desired mount path.

```ruby
# config/routes.rb
Rails.application.routes.draw do
  # Mount at custom path
  mount Marksmith::Engine => Marksmith.configuration.mount_path

  # Or mount at a specific path
  mount Marksmith::Engine => "/my-markdown-editor"
end
```

--------------------------------

### Register Marksmith Controllers

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Register the `MarksmithController` and `ListContinuationController` with StimulusJS for features like list continuation.

```javascript
import { ListContinuationController, MarksmithController } from '@avo-hq/marksmith'
// or /core for the no-dependencies version
import { ListContinuationController, MarksmithController } from '@avo-hq/marksmith/core'

application.register('marksmith', MarksmithController)
application.register('list-continuation', ListContinuationController)
```

--------------------------------

### Manually Mount Marksmith Engine

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Manually mount the Marksmith engine in your application's routes file if automatic mounting is disabled.

```ruby
# config/routes.rb
Rails.application.routes.draw do
  mount Marksmith::Engine => Marksmith.configuration.mount_path
end
```

--------------------------------

### Custom Marksmith Renderer

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Define a custom renderer by overriding the `Marksmith::Renderer` model to implement custom rendering logic.

```ruby
# 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
```

--------------------------------

### Enable Dark Mode with HTML Tag

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Apply dark mode to Marksmith rendered content by adding the 'dark' class to the `<html>` tag.

```erb
<!-- or -->
<html class="dark">
  <%= marksmith_tag :body %>
</html>
```

--------------------------------

### Basic Marksmith Tag Usage

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Use this ERB tag to render the Marksmith editor for a given attribute.

```erb
<%= marksmith_tag :body %>
```

--------------------------------

### Marksmith Integration with form_with

Source: https://context7.com/avo-hq/marksmith/llms.txt

Integrate Marksmith into a `form_with` builder by using the `form.marksmith` method for the markdown content field. This allows for standard form submission with markdown editing capabilities.

```erb
<!-- With form_with -->
<%= form_with model: @post do |form| %>
  <div class="field">
    <%= form.label :title %>
    <%= form.text_field :title %>
  </div>

  <div class="field">
    <%= form.label :body %>
    <%= form.marksmith :body, placeholder: "Write your post content..." %>
  </div>

  <%= form.submit "Save Post" %>
<% end %>
```

--------------------------------

### Include Marksmith Stylesheet

Source: https://context7.com/avo-hq/marksmith/llms.txt

Include the Marksmith stylesheet in your application's layout file to style the editor and rendered markdown. The `marksmith_asset_tags` helper can be used for convenience.

```erb
<!-- app/views/layouts/application.html.erb -->
<!DOCTYPE html>
<html>
  <head>
    <%= stylesheet_link_tag "marksmith" %>
    <!-- or use the combined helper -->
    <%= marksmith_asset_tags %>
  </head>
  <body>
    <%= yield %>
  </body>
</html>
```

--------------------------------

### Marksmith Field Options Configuration

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Configure Marksmith editor fields with options like disabled, placeholder, and file upload settings.

```erb
<%= marksmith_tag :body,
  disabled: true,
  placeholder: "Write your best markdown here.",
  extra_preview_params: { foo: "bar" },
  enable_file_uploads: true,
  upload_url: nil
  %>
```

--------------------------------

### Register Marksmith Stimulus Controllers

Source: https://context7.com/avo-hq/marksmith/llms.txt

Register the Marksmith and ListContinuation Stimulus controllers in your application's JavaScript index file to enable editor functionality.

```javascript
import { Application } from "@hotwired/stimulus"
import { MarksmithController, ListContinuationController } from '@avo-hq/marksmith'

const application = Application.start()

application.register('marksmith', MarksmithController)
application.register('list-continuation', ListContinuationController)
```

--------------------------------

### Render Markdown in ERB View

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Use the `marksmithed` helper in your ERB views to render Markdown content. Ensure content is sanitized to prevent XSS attacks when using `<%==`.

```erb
<%== marksmithed post.body %>
```

--------------------------------

### Integrating Marksmith with Avo

Source: https://context7.com/avo-hq/marksmith/llms.txt

Register Marksmith as a field type within Avo resources.

```ruby
# app/avo/resources/post_resource.rb
class PostResource < Avo::BaseResource
  self.title = :title

  field :id, as: :id
  field :title, as: :text

  # Use the markdown/marksmith field
  field :body, as: :markdown
  # or
  field :content, as: :marksmith

  # With options
  field :description, as: :markdown,
    extra_preview_params: { context: "admin" },
    file_uploads: true,
    media_library: true  # Enable Avo Media Library integration
end
```

--------------------------------

### Add Marksmith Gem Manually

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Manually add the marksmith gem and a markdown parser like commonmarker to your application's Gemfile.

```ruby
# Gemfile
gem "marksmith"
# Add a markdown parser
gem "commonmarker"
```

--------------------------------

### Enable Dark Mode with Marksmith Tag

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Apply dark mode to Marksmith rendered content by adding the 'dark' class to a wrapper element when using the `marksmith_tag` helper.

```erb
<!-- Wrapper element -->
<div class="dark">
  <%= marksmith_tag :body %>
</div>
```

--------------------------------

### Basic Marksmith Tag Usage

Source: https://context7.com/avo-hq/marksmith/llms.txt

Use the `marksmith_tag` helper to create a standalone markdown editor field outside of a Rails form builder. It accepts a field name and an optional initial value.

```erb
<!-- Basic usage -->
<%= marksmith_tag :body %>

<!-- With initial value -->
<%= marksmith_tag :body, value: "### Hello World\n\nThis is **bold** text." %>
```

--------------------------------

### Enable Dark Mode in Form with Marksmith Field

Source: https://github.com/avo-hq/marksmith/blob/main/README.md

Apply dark mode to Marksmith rendered content within a form by adding the 'dark' class to the form element when using the `form.marksmith` field.

```erb
<!-- or -->
<%= form_with model: post, class: "dark" do |form|
  <%= form.marksmith :body %>
<% end %>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.