Refactor Middleman Blogging for making guides

Gemfile

@@ -20,26 +20,26 @@ gem 'require_all', '1.3.3'
 gem 'middleman-autoprefixer', '~>2.7.0'
 
 # Use sprokets for assets + compass
-gem 'middleman-sprockets', '4.0.0'
 gem 'middleman-compass', '4.0.1'
+gem 'middleman-sprockets', '4.0.0'
+
+# Generating articles
+gem 'middleman-blog', '~> 4.0'
 
 # Boostrap as SASS
-gem 'sass', '3.4.19'
 gem 'bootstrap', '~> 4.0.0.alpha4'
 gem 'rails-assets-tether', '>= 1.1.0'
+gem 'sass', '3.4.19'
 
 # Grab jQuery
 gem 'jquery-middleman', '3.1.2'
 
 # Markdown redcarpet parsing engine + syntax highlighter for middleman
-gem 'redcarpet', '3.3.3'
 gem 'middleman-syntax', '~>3.0.0'
+gem 'redcarpet', '3.3.3'
 
 # Publish middleman website to gh-pages
 gem 'middleman-gh-pages', '~>0.3.0'
 
 # Rake tasks
 gem 'rake', '10.5.0'
-
-# Nokogiri for parsing HTML tags
-gem 'nokogiri'

Gemfile.lock

@@ -70,6 +70,10 @@ GEM
     middleman-autoprefixer (2.7.0)
       autoprefixer-rails (>= 6.3.1, < 7.0.0)
       middleman-core (>= 3.3.3)
+    middleman-blog (4.0.2)
+      addressable (~> 2.3)
+      middleman-core (~> 4.0)
+      tzinfo (>= 0.3.0)
     middleman-cli (4.1.10)
       thor (>= 0.17.0, < 2.0)
     middleman-compass (4.0.1)
@@ -110,11 +114,8 @@ GEM
     middleman-syntax (3.0.0)
       middleman-core (>= 3.2)
       rouge (~> 2.0)
-    mini_portile2 (2.2.0)
     minitest (5.9.0)
     multi_json (1.12.1)
-    nokogiri (1.8.0)
-      mini_portile2 (~> 2.2.0)
     padrino-helpers (0.13.2)
       i18n (~> 0.6, >= 0.6.7)
       padrino-support (= 0.13.2)
@@ -154,12 +155,12 @@ DEPENDENCIES
   jquery-middleman (= 3.1.2)
   middleman (~> 4.1.0)
   middleman-autoprefixer (~> 2.7.0)
+  middleman-blog (~> 4.0)
   middleman-compass (= 4.0.1)
   middleman-gh-pages (~> 0.3.0)
   middleman-livereload (~> 3.4.0)
   middleman-sprockets (= 4.0.0)
   middleman-syntax (~> 3.0.0)
-  nokogiri
   rails-assets-tether (>= 1.1.0)
   rake (= 10.5.0)
   redcarpet (= 3.3.3)

README.md

@@ -40,6 +40,11 @@ $ bundle exec middleman
 
 Your website will be watched and hosted locally at **[http://localhost:4567/](http://localhost:4567/)**.
 
+## Bootstrap
+
+We currently rely on a [Ruby Bootstrap gem](https://github.com/twbs/bootstrap-rubygem/tree/v4.0.0.alpha4) compiled with Bootstrap 4.0.0-alpha4.
+Relevant SASS files can be found [here](https://github.com/twbs/bootstrap-rubygem/tree/v4.0.0.alpha4/assets/stylesheets).
+
 ## Publishing
 
 Publish using:

config.rb

@@ -14,6 +14,15 @@
 # Automatic image dimensions on image_tag helper
 activate :automatic_image_sizes
 
+# Activate 'blogging' to generate guides
+activate :blog do |guide|
+  guide.prefix = 'articles/guides'
+  guide.default_extension = '.md'
+  guide.permalink = 'tags/{tags}/{title}.html'
+  guide.layout = :'articles/guides'
+  guide.tag_template = "#{guide.prefix}/tag_template.html"
+end
+
 # Reload the browser automatically whenever files change
 configure :development do
   activate :livereload
@@ -22,11 +31,11 @@
 # Methods defined in the helpers block are available in templates
 helpers do
   # Require all functions in the helpers directory
-  require_all 'helpers'
+  require_all 'lib/helpers'
 end
 
-# Helpers for string
-require 'lib/core_ext/string'
+# All overrides for core extensions
+require_all 'lib/core_ext'
 
 # Activate sprokets + compass
 activate :sprockets
@@ -41,6 +50,9 @@
 # Set the image directory to be ./images
 set :images_dir, 'images'
 
+# Partials must be from partials directory
+set :partials_dir, 'partials'
+
 # Activate markdown using Redcarpet parsing engine and syntax highlighting
 set :markdown_engine, :redcarpet
 set :markdown, fenced_code_blocks: true, smartypants: true
@@ -65,28 +77,28 @@
 # Page options, layouts, aliases and proxies
 ###
 
-# Root Layout
+# Specify the root layout to index
 page '/index.html', layout: :index
-# Article layout
-page '/articles/*', layout: :'articles/index'
-
-# Specific code guide layout
-page '/guides/code-examples/**/*.html', layout: :'articles/code-guide'
 
-# Guides layout (use article)
-page '/guides/*', layout: :'articles/index'
+# Specify layouts for subdirectories of articles _in order_ of application
+page '/articles/installation/**/step*', layout: :'articles/installation'
+page '/articles/installation/*', layout: :'articles/index'
+page '/articles/guides/index.html', layout: :'articles/index'
+page '/articles/guides/tags/*', layout: :'articles/guides'
+page '/articles/guides/tags/**/*', layout: :'articles/guides'
+page '/articles/contributing/*', layout: :'articles/index'
+page '/articles/index.html', layout: :'articles/index'
 
 # API proxy pages
 data.api.each do |api_group, data|
   name = api_group.to_human_case
-  guides = find_guides_in_category('code-examples/' << name.downcase)
   types = (data.typedefs + data.structs + data.enums).sort_by { |h| h[:name] }
   locals = {
     raw_api_data: data,
+    api_group: api_group,
     name: name,
     types: types,
     functions: data.functions,
-    guides: guides,
     defines: data.defines,
     description: data.description,
     brief: data.brief

lib/core_ext/string.rb

@@ -1,4 +1,4 @@
-require 'helpers/slug'
+require 'lib/helpers/slug'
 
 HUMANIZED_STRINGS = YAML.load_file('data/humanize.yml').freeze
 
@@ -13,6 +13,10 @@ def to_human_case
       selff.tr('_', ' ')
     end
 
+    def to_title_case
+      split(/[_\s]/).map(&:capitalize).join(' ')
+    end
+
     def to_kebab_case
       to_human_case.downcase.tr(' ', '-')
     end

lib/helpers/guides_for_function.rb

@@ -0,0 +1,14 @@
+# Returns all blog guides that are relevant for this function.
+# Essentially a lookup to which guides apply to the API group that
+# owns the function.
+def guides_for_function(guides, function)
+  guides.select do |guide|
+    guide.metadata[:page][:related_funcs].include?(function.name)
+  end
+end
+
+def guides_for_api_group(api_name)
+  blog.tags.map do |tag_name, tag_data|
+    tag_data if tag_name == api_name
+  end.flatten.compact
+end

helpers/sitemap_page_title.rb → lib/helpers/sitemap_page_title.rb

@@ -13,7 +13,7 @@ def sitemap_page_title
   # (i.e. getting started/foo/index.html -> getting started - foo)
   dest_path = dest_path.split('/')[0...-1].join(' - ')
   # Capitalize every word
-  page_title = dest_path.split.map { |s| s.to_human_case }.join(' ')
+  page_title = dest_path.split.map(&:to_human_case).join(' ')
   # Return nil if no page title, or the page_title
   !page_title.strip.empty? ? page_title : nil
 end

source/api/template.html.erb

@@ -7,33 +7,53 @@
 <%# Functions %>
 <% if !functions.empty? %>
   <section class="sk-api-functions">
-    <% if !guides.empty? %>
+    <% guides = guides_for_api_group(api_group) %>
+    <% unless guides.empty? %>
     <section class="sk-api-guides">
       <h2><%= name %> Guides</h2>
-      <% guides.each do |f| %>
-        <a class="btn btn-primary btn-sm" target="_blank" href="/<%= f[:uri] %>"><%= f[:doc_title] %></a>
+      <% guides.each do |guide| %>
+        <%= link_to guide.title, guide, class: 'btn btn-primary btn-sm', target: '_blank' %>
       <% end %>
     </section>
     <% end %>
     <h2> Functions </h2>
+    <%# Group by functions %>
     <% functions.group_by { |fn| fn.name }.each do |group, functions| %>
-      <section class="sk-api-function sk-api-section" <%= "style='display:none'" unless functions.length > 1 %>>
-        <h3 id="group-<%= slug_for group %>" data-anchor> <%= group.to_human_case %> </h3>
-        <div class="sk-api-description">
-          There are multiple versions of <%= group.to_human_case %>:
-          <ul>
-            <% functions.each do |function| %>
-              <li>
-                <a href="<%= slug_url_for(function) %>">
-                  <%= group.to_human_case %> ( <%= function.parameters.map {|param_name, param_data| param_data.type.to_human_case }.join(", ") %> )
-                </a>
-              </li>
-            <% end %>
-          </ul>
-        </div>
-      </section>
+      <% if functions.length > 1 %>
+        <section class="sk-api-function sk-api-section">
+          <h3 id="group-<%= slug_for group %>" data-anchor>
+            <%= group.to_human_case %>
+            <label class="tag tag-pill tag-primary pull-right">
+              Overloaded
+            </label>
+          </h3>
+          <div class="sk-api-overloaded">
+            <div class="card">
+              <div class="card-header">
+                This function is overloaded. The following versions exist.
+              </div>
+              <ul class="list-group list-group-flush">
+                <% functions.each do |function| %>
+                  <li class="list-group-item">
+                    <% link_to slug_url_for(function) do %>
+                      <strong><%= group.to_human_case %></strong>
+                      (
+                        <% function.parameters.each do |param_name, param_data| %>
+                          <em><%= param_name %></em>
+                          :
+                          <code><%= param_data.type.to_human_case %></code>
+                        <% end %>
+                      )
+                    <% end %>
+                  </li>
+                <% end %>
+              </ul>
+            </div>
+          </div>
+        </section>
+      <% end %>
       <% functions.each do |function| %>
-        <%= partial 'partials/api/function', locals: { function: function } %>
+        <%= partial 'partials/api/function', locals: { function: function, guides: guides } %>
       <% end %>
     <% end %>
   </section>