Madmin Documentation

To prevent non-admin users from even discovering the /madmin path, wrap your Madmin namespace in an authenticated block within config/routes.rb. Using authenticated is recommended over authenticate because it causes the route to return a 404 for unauthorized users, which helps hide the admin area from malicious attempts.

authenticated :user, lambda { |u| u.admin? } do
  namespace :madmin do
  end
end

To create a new custom field type in Madmin, use the madmin:field generator. This creates a CustomField class in app/madmin/fields/custom_field.rb and generates the necessary partial views for the Madmin interface.

rails g madmin:field Custom

Madmin provides a generator to copy its default views into your Rails application. Once copied, you can modify these files to customize the admin interface's appearance and behavior. Running this generator copies all views used for every resource into your application.

rails generate madmin:views

To include custom stylesheets from your Rails application's asset pipeline in the Madmin interface, append the stylesheet name to the Madmin.stylesheets array. This is typically done in a Madmin initializer. The name should correspond to the file in app/assets/stylesheets/ (without the .css extension).

Madmin.stylesheets << "my_stylesheet"

For a simple authentication layer, you can use http_basic_authenticate_with inside app/controllers/madmin/application_controller.rb. It is best practice to pull the credentials from environment variables or Rails credentials.

module Madmin
  class ApplicationController < Madmin::BaseController
    http_basic_authenticate_with(
      name: ENV['ADMIN_USERNAME'] || Rails.application.credentials.admin_username,
      password: ENV['ADMIN_PASSWORD'] || Rails.application.credentials.admin_password
    )
  end
end

When you generate a Madmin resource, the generator creates a matching controller file that you can override to implement custom logic. For example, running rails g madmin:resource Post will generate app/controllers/madmin/posts_controller.rb.

To understand the available methods and the structure of standard actions, you should refer to the base Madmin::ResourceController class.

# Example command that generates a custom controller
rails g madmin:resource Post

To add JavaScript packages to the Madmin interface, use Madmin.importmap.draw. This method accepts a path to a file containing your importmap lines. This is useful for integrating Gem-specific importmaps into the admin layout.

Madmin.importmap.draw HotwireCombobox::Engine.root.join("config/hw_importmap.rb")

To install Madmin, add the gem to your Gemfile and run the installation generator. The generator will install the gem and automatically create resources for every model it detects in your application.

bundle add madmin
rails g madmin:install

Available view generators:

• All views: rails generate madmin:views (includes index, new, edit, show, _form, application layout, javascript, and navigation)
• Navigation only: rails g madmin:views:navigation -> app/views/madmin/_navigation.html.erb
• Layout files: rails g madmin:views:layout (includes layout, javascript, and navigation) -> app/views/madmin/application.html.erb, app/views/madmin/_javascript.html.erb, app/views/madmin/_navigation.html.erb
• Specific action: rails g madmin:views:index -> app/views/madmin/application/index.html.erb
• Scoped to a model: rails generate madmin:views:index Book -> app/views/madmin/books/index.html.erb

To include stylesheets provided by a Gem (for example, Hotwire Combobox), append the asset name to the Madmin.stylesheets array in a Madmin initializer. Madmin will resolve these assets through the Rails asset pipeline.

Madmin.stylesheets << "hotwire_combobox"

If the built-in field types are insufficient, you can generate a custom field class. This creates the class file and the necessary partials for the form, index, and show views.

rails g madmin:field Custom

After generating, use it in a resource:

class PostResource < Madmin::Resource
  attribute :title, field: CustomField
end