+
+
+
+
+
diff --git a/docs/adding_custom_field_types.md b/docs/adding_custom_field_types.md
new file mode 100644
index 0000000000..8c4d5c43ab
--- /dev/null
+++ b/docs/adding_custom_field_types.md
@@ -0,0 +1,59 @@
+# Adding Custom Field Types
+
+If your application deals with a nonstandard data type,
+you can create an `Administrate::Field` object to help display
+the custom data type across the dashboard.
+
+`Administrate::Field` objects consist of two parts:
+a Ruby class and associated views.
+
+For example, let's create a `Field` that displays [Gravatars] based on an email.
+
+[Gravatars]: https://gravatar.com/
+
+First, we'll run a generator to set us up with the files we need:
+
+```bash
+rails generate administrate:field gravatar
+```
+
+This creates a few files:
+
+- `app/fields/gravatar_field.rb`
+- `app/views/fields/gravatar_field/_show.html.erb`
+- `app/views/fields/gravatar_field/_index.html.erb`
+- `app/views/fields/gravatar_field/_form.html.erb`
+
+We can edit the `app/fields/gravatar_field.rb` to add some custom logic:
+
+```ruby
+# app/fields/gravatar_field.rb
+require 'digest/md5'
+
+class GravatarField < Administrate::Field::Base
+ def gravatar_url
+ email_address = data.downcase
+ hash = Digest::MD5.hexdigest(email_address)
+ "http://www.gravatar.com/avatar/#{hash}"
+ end
+end
+```
+
+Next, we can customize the partials to display data how we'd like.
+Open up the `app/views/fields/gravatar_field/_show.html.erb` partial.
+By default, it looks like:
+
+```eruby
+<%= field.data %>
+```
+
+Since we want to display an image, we can change it to:
+
+```eruby
+<%= image_tag field.gravatar_url %>
+```
+
+You can customize the other generated partials in the same way
+for custom behavior on the index and form pages.
+
+[Customizing Attribute Partials]: /customizing_attribute_partials
diff --git a/docs/customizing_attribute_partials.md b/docs/customizing_attribute_partials.md
new file mode 100644
index 0000000000..fe7ac55454
--- /dev/null
+++ b/docs/customizing_attribute_partials.md
@@ -0,0 +1,34 @@
+# Customizing attribute partials
+
+Occasionally you might want to change how specific types of attributes appear
+across all dashboards.
+For example, you might want all `Number` values to round to three decimal points.
+
+To get started, run the appropriate rails generator:
+
+```bash
+rails generate administrate:views:field number
+```
+
+This will generate three files:
+
+- `app/view/fields/form/_number.html.erb`
+- `app/view/fields/index/_number.html.erb`
+- `app/view/fields/show/_number.html.erb`
+
+The generated templates will have documentation
+describing which variables are in scope.
+The rendering part of the partial will look like:
+
+```eruby
+<%= field.data %>
+```
+
+Changing numbers to display to three decimal places might look like this:
+
+```eruby
+<%= field.data.round(3) %>
+```
+
+If you only want to change how an attribute appears
+on a single page (e.g. `index`), you may delete the unnecessary templates.
diff --git a/docs/customizing_controller_actions.md b/docs/customizing_controller_actions.md
new file mode 100644
index 0000000000..e9136af318
--- /dev/null
+++ b/docs/customizing_controller_actions.md
@@ -0,0 +1,32 @@
+# Customizing controller actions
+
+When you install Administrate into your app,
+we generate empty controllers for each of your resources.
+If you want to create more complex application behavior for a dashboard,
+simply overwrite controller actions.
+
+The generated controller will look something like:
+
+```ruby
+# app/controllers/admin/foos_controller.rb
+
+class Admin::FoosController < Admin::ApplicationController
+
+ # Overwrite any of the RESTful controller actions to implement custom behavior
+ # For example, you may want to send an email after a foo is updated.
+ #
+ # def update
+ # foo = Foo.find(params[:id])
+ # foo.update(params[:foo])
+ # send_foo_updated_email
+ # end
+
+ # Override this method to specify custom lookup behavior.
+ # This will be used to set the resource for the `show`, `edit`, and `update`
+ # actions.
+ #
+ # def find_resource(param)
+ # Foo.find_by!(slug: param)
+ # end
+end
+```
diff --git a/docs/customizing_dashboards.md b/docs/customizing_dashboards.md
new file mode 100644
index 0000000000..b157027b81
--- /dev/null
+++ b/docs/customizing_dashboards.md
@@ -0,0 +1,79 @@
+# Customizing Dashboards
+
+In order to customize which attributes get displayed for each resource,
+edit the dashboard file generated by the installation generator.
+
+By default, the file will look something like this:
+
+```ruby
+require "administrate/dashboard/base"
+
+class CustomerDashboard < Administrate::Dashboard::Base
+ ATTRIBUTE_TYPES = {
+ id: Field::Integer,
+ name: Field::String,
+ email: Field::String,
+ created_at: Field::DateTime,
+ updated_at: Field::DateTime,
+ orders: Field::HasMany,
+ }
+
+ COLLECTION_ATTRIBUTES = [
+ :id,
+ :name,
+ :email,
+ :created_at,
+ :updated_at,
+ :orders,
+ ]
+
+ SHOW_PAGE_ATTRIBUTES = [
+ :id,
+ :name,
+ :email,
+ :created_at,
+ :updated_at,
+ :orders,
+ ]
+
+ FORM_ATTRIBUTES = [
+ :name,
+ :email,
+ :orders,
+ ]
+end
+```
+
+To change which attributes appear on each of the `index`, `show`, and `edit`
+pages, add or remove attributes to each constant array.
+
+Finally, the `ATTRIBUTE_TYPES` method defines how each attribute is displayed
+throughout the dashboard. There are a number of `Field` classes that you can
+specify, including:
+
+- `Field::BelongsTo`
+- `Field::Boolean`
+- `Field::DateTime`
+- `Field::Email`
+- `Field::HasMany`
+- `Field::HasOne`
+- `Field::Image`
+- `Field::Number`
+- `Field::Polymorphic`
+- `Field::String`
+
+Each of the `Field` types take a different set of options,
+which are specified through the `.with_options` class method.
+For example, you might use the following to display currency,
+if the value is stored by the number of cents:
+
+```ruby
+ unit_price_in_cents: Field::Number.with_options(
+ title: "Unit Price",
+ prefix: "$",
+ multiplier: 0.01,
+ decimals: 2,
+ )
+```
+
+[define your own]: /adding_custom_field_types
diff --git a/docs/customizing_page_views.md b/docs/customizing_page_views.md
new file mode 100644
index 0000000000..b83553b674
--- /dev/null
+++ b/docs/customizing_page_views.md
@@ -0,0 +1,65 @@
+# Customizing page views
+
+In order to change the appearance of any page,
+you can write custom Rails views.
+
+## Customizing for all resources
+
+The easiest way to get started is by using the built-in generators.
+In order to change the appearance of views for all resource types,
+call the generators with no arguments.
+
+```bash
+rails generate administrate:views:index
+ # -> app/views/administrate/application/index.html.erb
+ # -> app/views/administrate/application/_table.html.erb
+
+rails generate administrate:views:show
+ # -> app/views/administrate/application/show.html.erb
+
+rails generate administrate:views:edit
+ # -> app/views/administrate/application/edit.html.erb
+ # -> app/views/administrate/application/_form.html.erb
+
+rails generate administrate:views:new
+ # -> app/views/administrate/application/new.html.erb
+ # -> app/views/administrate/application/_form.html.erb
+
+rails generate administrate:views
+ # -> all of the above
+```
+
+The generators copy over the default views that Administrate uses,
+so you have a good starting point for customizations.
+Feel free to change up the file type,
+add extra sections to the page,
+or blow it all away for your own custom look.
+
+## Customizing for a specific resource
+
+In order to change a dashboard page for a single type of resource,
+pass in the resource name to the view generators.
+
+```bash
+rails generate administrate:views:index User
+ # -> app/views/administrate/users/index.html.erb
+ # -> app/views/administrate/users/_table.html.erb
+
+rails generate administrate:views:show User
+ # -> app/views/administrate/users/show.html.erb
+
+rails generate administrate:views:edit User
+ # -> app/views/administrate/users/edit.html.erb
+ # -> app/views/administrate/users/_form.html.erb
+
+rails generate administrate:views:new User
+ # -> app/views/administrate/users/new.html.erb
+ # -> app/views/administrate/users/_form.html.erb
+
+rails generate administrate:views User
+ # -> all of the above
+```
+
+Any changes to these template files
+will *only* affect pages that display customers,
+and will leave the show pages for other resources unchanged.
diff --git a/docs/getting_started.md b/docs/getting_started.md
new file mode 100644
index 0000000000..924bebc95d
--- /dev/null
+++ b/docs/getting_started.md
@@ -0,0 +1,54 @@
+# Getting Started
+
+Administrate is released as a Ruby gem, and can be installed on Rails
+applications version 4.2 or greater.
+
+Add the following to your Gemfile:
+
+```ruby
+# Gemfile
+gem "administrate"
+```
+
+Re-bundle, then run the installer:
+
+```bash
+$ rails generate administrate:install
+```
+
+The installer creates a few files.
+Two of them are standard for any installation:
+
+- `app/controllers/admin/application_controller.rb`
+- `app/dashboards/dashboard_manifest.rb`
+
+In addition, the generator creates a `Dashboard` and a `Controller` for each of
+your ActiveRecord resources:
+
+- `app/controllers/admin/foos_controller.rb`
+- `app/dashboards/foo_dashboard.rb`
+
+The `Admin::ApplicationController` can be customized to add
+authentication logic, authorization, pagination,
+or other controller-level concerns.
+
+The `DashboardManifest` can be customized to show or hide
+different models on the dashboard.
+
+Each `FooDashboard` specifies which attributes should be displayed
+on the admin dashboard for the `Foo` resource.
+
+Each `Admin::FooController` can be overwritten to specify custom behavior.
+
+The installer will also add a line to your `config/routes.rb` file:
+
+```ruby
+DashboardManifest.new.dashboards.each do |dashboard_resource|
+ resources dashboard_resource
+end
+
+root controller: DashboardManifest.new.root_dashboard, action: :index
+```
+
+Feel free to customize these routes to your heart's content,
+then visit to see your new dashboard in action.
diff --git a/spec/example_app/config/initializers/assets.rb b/spec/example_app/config/initializers/assets.rb
index 13abef88e1..cce35ba935 100644
--- a/spec/example_app/config/initializers/assets.rb
+++ b/spec/example_app/config/initializers/assets.rb
@@ -9,3 +9,4 @@
# Precompile additional assets.
# application.js, application.css, and all non-JS/CSS in app/assets folder are already added.
# Rails.application.config.assets.precompile += %w( search.js )
+Rails.application.config.assets.precompile += %w( docs.css )
diff --git a/spec/example_app/config/initializers/markdown.rb b/spec/example_app/config/initializers/markdown.rb
new file mode 100644
index 0000000000..be8550f8cf
--- /dev/null
+++ b/spec/example_app/config/initializers/markdown.rb
@@ -0,0 +1,11 @@
+MarkdownRails.configure do |config|
+ markdown = Redcarpet::Markdown.new(
+ Redcarpet::Render::HTML,
+ fenced_code_blocks: true,
+ autolink: true,
+ )
+
+ config.render do |markdown_source|
+ markdown.render(markdown_source)
+ end
+end
diff --git a/spec/example_app/config/routes.rb b/spec/example_app/config/routes.rb
index 13f5c6fe7c..e6a0de7477 100644
--- a/spec/example_app/config/routes.rb
+++ b/spec/example_app/config/routes.rb
@@ -7,5 +7,6 @@
root controller: DashboardManifest::ROOT_DASHBOARD, action: :index
end
- root to: redirect("/admin")
+ get "/:page", to: "docs#show"
+ root to: "docs#index"
end