diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dcaaff685e..da183d4c32 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,6 @@ -# Contributing Guide +--- +title: Contributing Guide +--- ## Code of Conduct @@ -24,7 +26,7 @@ To maintain compatibility with multiple dependency versions, we use ### Opening a PR 1. Fork the repo, -2. Run `./bin/setup` to install the base dependencies and setup a local +2. Run `./bin/setup` to install the base dependencies and setup a local database, 3. Run the test suite: `bundle exec rspec && bundle exec appraisal rspec`, 4. Make your changes, diff --git a/Gemfile b/Gemfile index f638614366..7ef5899244 100644 --- a/Gemfile +++ b/Gemfile @@ -5,6 +5,7 @@ gemspec gem "administrate-field-image" gem "autoprefixer-rails" gem "faker" +gem "front_matter_parser" gem "globalid" gem "pg" gem "redcarpet" diff --git a/Gemfile.lock b/Gemfile.lock index 360b870ead..bf844de804 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -99,6 +99,7 @@ GEM activesupport capybara i18n + front_matter_parser (0.2.1) globalid (0.4.2) activesupport (>= 4.2.0) hashdiff (1.0.0) @@ -265,6 +266,7 @@ DEPENDENCIES factory_bot_rails faker formulaic + front_matter_parser globalid i18n-tasks (= 0.9.30) launchy diff --git a/README.md b/README.md index dc6dde381e..926d296cce 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,7 @@ -# Administrate +--- +title: Administrate +home: true +--- [![CircleCI](https://img.shields.io/circleci/project/github/thoughtbot/administrate.svg)](https://circleci.com/gh/thoughtbot/administrate/tree/master) [![Gem Version](https://badge.fury.io/rb/administrate.svg)](https://badge.fury.io/rb/administrate) diff --git a/docs/adding_custom_field_types.md b/docs/adding_custom_field_types.md index bc1191e4b8..a75644d415 100644 --- a/docs/adding_custom_field_types.md +++ b/docs/adding_custom_field_types.md @@ -1,4 +1,6 @@ -# Adding Custom Field Types +--- +title: Adding Custom Field Types +--- If your application deals with a nonstandard data type, you can create an `Administrate::Field` object to help display diff --git a/docs/authentication.md b/docs/authentication.md index 91a4285c03..548a36a279 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,4 +1,6 @@ -# Authenticating admin users +--- +title: Authenticating admin users +--- Authentication is left for you to implement after you install Administrate into your app. It's expected that you can plugin your existing authentication diff --git a/docs/authorization.md b/docs/authorization.md index 2c5548add6..8e84875f0a 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -1,4 +1,6 @@ -# Authorization +--- +title: Authorization +--- The default configuration of Administrate is "authenticate-only" - once a user is authenticated, that user has access to every action of every object. @@ -37,7 +39,7 @@ class PostPolicy < ApplicationPolicy def resolve scope.all end - + def resolve_admin scope.where(owner: user) end @@ -62,7 +64,7 @@ def authorize_resource(resource) raise "Erg!" unless show_action?(params[:action], resource) end -# Hide links to actions if the user is not allowed to do them +# Hide links to actions if the user is not allowed to do them def show_action?(action, resource) current_user.can? action, resource end diff --git a/docs/customizing_attribute_partials.md b/docs/customizing_attribute_partials.md index 1be446e1c2..ceb02ed45b 100644 --- a/docs/customizing_attribute_partials.md +++ b/docs/customizing_attribute_partials.md @@ -1,4 +1,6 @@ -# Customizing attribute partials +--- +title: Customizing attribute partials +--- Occasionally you might want to change how specific types of attributes appear across all dashboards. You can customize the following built in field types: diff --git a/docs/customizing_controller_actions.md b/docs/customizing_controller_actions.md index c0f058c19a..c333050863 100644 --- a/docs/customizing_controller_actions.md +++ b/docs/customizing_controller_actions.md @@ -1,4 +1,6 @@ -# Customizing controller actions +--- +title: Customizing controller actions +--- When you install Administrate into your app, we generate empty controllers for each of your resources. diff --git a/docs/customizing_dashboards.md b/docs/customizing_dashboards.md index 42fcef90ef..ffaaf8d998 100644 --- a/docs/customizing_dashboards.md +++ b/docs/customizing_dashboards.md @@ -1,4 +1,6 @@ -# Customizing Dashboards +--- +title: Customizing Dashboards +--- In order to customize which attributes get displayed for each resource, edit the dashboard file generated by the installation generator. diff --git a/docs/customizing_page_views.md b/docs/customizing_page_views.md index d283ed938a..23ece20c37 100644 --- a/docs/customizing_page_views.md +++ b/docs/customizing_page_views.md @@ -1,4 +1,6 @@ -# Customizing page views +--- +title: Customizing page views +--- In order to change the appearance of any page, you can write custom Rails views. diff --git a/docs/getting_started.md b/docs/getting_started.md index 8d9ba72f6b..72f645f6b1 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,4 +1,6 @@ -# Getting Started +--- +title: Getting Started +--- Administrate is released as a Ruby gem, and can be installed on Rails applications version 4.2 or greater. @@ -84,8 +86,8 @@ rails generate administrate:install --namespace=supervisor ## Keep Dashboards Updated as Model Attributes Change -If you've installed Administrate and generated dashboards and _then_ -subsequently added attributes to your models you'll need to manually add +If you've installed Administrate and generated dashboards and _then_ +subsequently added attributes to your models you'll need to manually add these additions (or removals) to your dashboards. Example: @@ -98,7 +100,7 @@ Example: the_new_attribute: Field::String, # ... }.freeze - + SHOW_PAGE_ATTRIBUTES = [ # ... :the_new_attribute, @@ -110,7 +112,7 @@ Example: :the_new_attribute, # ... ].freeze - + COLLECTION_ATTRIBUTES = [ # ... :the_new_attribute, # if you want it on the index, also. @@ -118,7 +120,7 @@ Example: ].freeze ``` -It's recommended that you make this change at the same time as you add the +It's recommended that you make this change at the same time as you add the attribute to the model. The alternative way to handle this is to re-run `rails g administrate:install` diff --git a/docs/rails_api.md b/docs/rails_api.md index e00d61670c..39f8676426 100644 --- a/docs/rails_api.md +++ b/docs/rails_api.md @@ -1,7 +1,9 @@ -## Rails API +--- +title: Rails API +--- Since Rails 5.0, we've been able to have API only applications. Yet, sometimes -we still want to have an admin. +we still want to have an admin. To get this working, we recommend updating this config: @@ -29,7 +31,7 @@ config.middleware.use ::Rack::MethodOverride ``` You must also ensure that all the required controller actions are available -and accessible as routes since generators in API-only applications only +and accessible as routes since generators in API-only applications only generate some of the required actions. Here is an example: ```ruby diff --git a/spec/example_app/app/controllers/docs_controller.rb b/spec/example_app/app/controllers/docs_controller.rb index dece8410b7..f551a24fab 100644 --- a/spec/example_app/app/controllers/docs_controller.rb +++ b/spec/example_app/app/controllers/docs_controller.rb @@ -18,7 +18,12 @@ def render_page(name) path = full_page_path(name) if File.exist?(path) - render layout: "docs", html: render_markdown(path).html_safe + contents = parse_document(path) + @page_title = contents.title + @page_title_suffix = contents.title_suffix + # rubocop:disable Rails/OutputSafety + render layout: "docs", html: contents.body.html_safe + # rubocop:enable Rails/OutputSafety else render file: "#{Rails.root}/public/404.html", layout: false, @@ -30,11 +35,44 @@ def full_page_path(page) Rails.root + "../../#{page}.md" end - def render_markdown(path) + def parse_document(path) text = File.read(path) - renderer = Redcarpet::Render::HTML - markdown = Redcarpet::Markdown.new(renderer, REDCARPET_CONFIG) + DocumentParser.new(text) + end + + class DocumentParser + def initialize(source_text) + front_matter_parsed = FrontMatterParser::Parser.new(:md).call(source_text) + @source_text = front_matter_parsed.content + @metadata = front_matter_parsed.front_matter + end + + def body + @body ||= + begin + renderer = Redcarpet::Render::HTML + markdown = Redcarpet::Markdown.new(renderer, REDCARPET_CONFIG) + + source_text_with_heading = <<~MARKDOWN + # #{title} + + #{source_text} + MARKDOWN + + markdown.render(source_text_with_heading) + end + end + + def title + metadata["title"] + end + + def title_suffix + metadata["home"] ? "" : " - Administrate" + end + + private - markdown.render(text) + attr_reader :source_text, :metadata end end diff --git a/spec/example_app/app/views/layouts/docs.html.erb b/spec/example_app/app/views/layouts/docs.html.erb index fe9096581c..484f90ed1f 100644 --- a/spec/example_app/app/views/layouts/docs.html.erb +++ b/spec/example_app/app/views/layouts/docs.html.erb @@ -2,6 +2,7 @@ + <%= @page_title %><%= @page_title_suffix %> <%= stylesheet_link_tag "docs", media: "all" %>