diff --git a/docs/_includes/custom/shuffle_panel.html b/docs/_includes/custom/shuffle_panel.html
index f537106ca6..46a0852917 100644
--- a/docs/_includes/custom/shuffle_panel.html
+++ b/docs/_includes/custom/shuffle_panel.html
@@ -15,8 +15,10 @@
 
 
 {% capture titlemaker %} {{ include.titlemaker | default: "page.title" }} {% endcapture %}
-{% assign include_tags = {{ include.tags | split: "," }} %}
-{% assign exclude_tags = {{ include.except_tags | split: "," }} %}
+{% assign include_tags = include.tags | split: "," %}
+{% assign exclude_tags = include.except_tags | split: "," %}
+
+{% assign sorted_pages = site.pages | sort_using: site.data.sidebars.pmd_sidebar %}
 
 
 <div class="col-xs-6 col-sm-4 col-md-4" data-groups='{{ include.datagroups }}'>
@@ -39,7 +41,7 @@
                 {{ include.description }}
             </p>
             <ul>
-                {% for page in site.pages %}
+                {% for page in sorted_pages %}
                     {% capture included %}{{ page.tags | intersect: include_tags | equals: include_tags }}{% endcapture %}
                     {% capture excluded %}{{ page.tags | intersect: exclude_tags | empty }}{% endcapture %}
 
diff --git a/docs/_plugins/custom_filters.rb b/docs/_plugins/custom_filters.rb
index a61e33e9e8..88845c6228 100644
--- a/docs/_plugins/custom_filters.rb
+++ b/docs/_plugins/custom_filters.rb
@@ -19,6 +19,64 @@ module CustomFilters
     Array(xs).empty?
   end
 
+
+  # print & pass
+  def pp(any)
+    puts "#{any}"
+    any
+  end
+
+  def flatten_rec(seq)
+    seq.map {|h|
+      if (subs = h["folderitems"] || h["subfolderitems"] || h["subfolders"])
+        flatten_rec(subs).flatten
+      elsif (page = h["url"])
+        page
+      end
+    }.flatten
+  end
+
+  def rank_lookup_from_sidebar(sidebar)
+
+    folders = sidebar["entries"][0]["folders"]
+
+    ordered = flatten_rec(folders).select {|url|
+      url && url.end_with?(".html")
+    }
+
+    Hash[ordered.zip (0...ordered.size)]
+
+  end
+
+
+
+  # sorts an array using the order defined by the given sidebar
+  def sort_using(xs, sidebar)
+    # caching is possible but doesn't improve significantly the build times
+
+
+    rank_lookup = rank_lookup_from_sidebar(sidebar)
+
+    xs.sort {|x, y|
+
+      rx = rank_lookup[x.url] || -1
+      ry = rank_lookup[y.url] || -1
+
+      if rx == ry
+        0
+      elsif rx < 0
+        +1 # x after y
+      elsif ry < 0
+        -1 # x before y
+      elsif rx < ry
+        -1
+      else
+        +1
+      end
+    }
+
+  end
+
 end
 
 Liquid::Template.register_filter(CustomFilters)
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 2638935647..7a7d0be257 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -12,9 +12,9 @@ author: Jeff Jensen <jjensen@apache.org>, Andreas Dangel <andreas.dangel@adangel
 ---
 
 
-## Welcome to PMD!
+<!-- ## Welcome to PMD! -->
 
-First time user? Then you may be interested in our [quickstart series](TODO)!
+<!-- First time user? Then you may be interested in our [quickstart series](TODO)! -->
 
 <br/>
 
@@ -24,6 +24,14 @@ First time user? Then you may be interested in our [quickstart series](TODO)!
 <script src="js/jquery.ba-throttle-debounce.min.js"></script>
 {% endunless %}
 
+
+
+
+<div class="col-lg-12">
+    <h2 class="page-header">Welcome to PMD!</h2>
+</div>
+
+
 <div class="filter-options">
       <button class="btn btn-primary" data-group="all">All</button>
       <button class="btn btn-primary" data-group="getting_started">Getting Started</button>
@@ -33,6 +41,9 @@ First time user? Then you may be interested in our [quickstart series](TODO)!
 </div>
 
 
+<!--  Initialize it, to speed up the rest -->
+
+
 <div id="grid" class="row">
 
     {% include custom/shuffle_panel.html
@@ -94,6 +105,7 @@ First time user? Then you may be interested in our [quickstart series](TODO)!
 
 
 
+
    <!-- {% include custom/shuffle_panel_filler.html %} -->
 
 </div>
diff --git a/docs/pages/pmd/userdocs/extending/rule_guidelines.md b/docs/pages/pmd/userdocs/extending/rule_guidelines.md
index b3cb03db69..91f03f6dba 100644
--- a/docs/pages/pmd/userdocs/extending/rule_guidelines.md
+++ b/docs/pages/pmd/userdocs/extending/rule_guidelines.md
@@ -1,5 +1,5 @@
 ---
-title: PMD Rule Guidelines
+title: Rule guidelines
 tags: [extending, userdocs]
 summary: Rule Guidelines
 last_updated: July 3, 2016
diff --git a/docs/pages/pmd/userdocs/extending/writing_pmd_rules.md b/docs/pages/pmd/userdocs/extending/writing_pmd_rules.md
index 1e99d8dcac..9dfd91fc41 100644
--- a/docs/pages/pmd/userdocs/extending/writing_pmd_rules.md
+++ b/docs/pages/pmd/userdocs/extending/writing_pmd_rules.md
@@ -1,7 +1,7 @@
 ---
-title:  PMD Writing a Custom Rule
+title:  Writing a custom rule
 tags: [extending, userdocs]
-summary: Writing a Custom Rule for PMD
+summary: "Learn how to write a custom rule for PMD"
 last_updated: July 3, 2016
 permalink: pmd_userdocs_extending_writing_pmd_rules.html
 author: Tom Copeland <tomcopeland@users.sourceforge.net>
diff --git a/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md b/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md
index 6221d76ebe..3934430c05 100644
--- a/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md
+++ b/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md
@@ -1,5 +1,5 @@
 ---
-title:  Writing XPath Rules
+title:  Writing XPath rules
 tags: [extending, userdocs]
 summary: "Writing XPath rules for PMD"
 last_updated: July 3, 2016