Provide <title> tags for doc pages (#1537)

Introducing YAML front matter allows us to specify manual titles for each page, which makes it easier to understand which page you're actually on. This is slightly more awkward when viewing `CONTRIBUTING.md` on GitHub, but having titles outweighs that problem.
thoughtbot · Feb 18, 2020 · 46beb19 · 46beb19
1 parent 990896c
commit 46beb19
Show file tree

Hide file tree

Showing 15 changed files with 91 additions and 26 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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`

diff --git 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
@@ -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
@@ -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">