Provide <title> tags for doc pages

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,

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"

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

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)

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

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

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

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:

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.

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.

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.

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,15 +112,15 @@ Example:
     :the_new_attribute,
     # ...
   ].freeze
-  
+
   COLLECTION_ATTRIBUTES = [
     # ...
     :the_new_attribute, # if you want it on the index, also.
     # ...
   ].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`

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

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

spec/example_app/app/views/layouts/docs.html.erb

@@ -2,6 +2,7 @@
 <html lang="en">
 <head>
   <meta charset="utf-8" />
+  <title><%= @page_title %><%= @page_title_suffix %></title>
   <%= stylesheet_link_tag "docs", media: "all" %>
   <link href='//fonts.googleapis.com/css?family=Lato|Source+Code+Pro|Fjalla+One' rel='stylesheet' type='text/css'>
   <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/default.min.css">