Merge pull request #12 from alexcu/develop

Refactor Middleman Blogging for making guides

Author: alexcu

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

helpers/guides.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/core_ext/string.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/active_class.rb lib/helpers/active_class.rbhelpers/active_class.rb renamed to lib/helpers/active_class.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