Add description to index page

docs/_includes/custom/panel_scroll.html

@@ -0,0 +1,29 @@
+<script src="../../js/jquery-ui.min.js"></script>
+
+<script>
+// Adds a pretty animation to links to shuffle panels
+$(function () {
+    $('a[href^=#shuffle-panel]').click(function () {
+        if (location.pathname.replace(/^\//, '') === this.pathname.replace(/^\//, '')
+            && location.hostname === this.hostname) {
+            var target = $(this.hash);
+
+            target = target.length ? target : $('[name=' + this.hash.slice(1) + ']');
+            if (target.length) {
+                $('html,body').animate({
+                    scrollTop: target.offset().top - 250,
+                }, {
+                    duration: 500,
+                    complete: function () {
+                        target.effect("highlight", {}, 1000);
+                    }
+                });
+
+                // $(this.hash).effect("highlight", {}, 3000);
+                // $(this.hash).toggle("highlight");
+                return false;
+            }
+        }
+    });
+});
+</script>

docs/_includes/custom/shuffle_panel.html

@@ -14,14 +14,14 @@
 <!-- titlemaker (optional) : name of a variable that's evaluated to determine the displayed title of the page. Default is page.title -->
 
 
-{% capture titlemaker %} {{ include.titlemaker | default: "page.title" }} {% endcapture %}
+{% assign titlemaker = include.titlemaker | default: "page.title" %}
 {% 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 %}
 
+{% assign panel_id = include.title | downcase | strip | replace: ' ', '-' | prepend: "shuffle-panel-" %}
 
-<div class="col-xs-6 col-sm-4 col-md-4" data-groups='{{ include.datagroups }}'>
+<div class="col-xs-6 col-sm-4 col-md-4" data-groups='{{ include.datagroups }}' id="{{ panel_id }}">
     <div class="panel panel-default">
 
 

docs/index.md

@@ -4,10 +4,9 @@ keywords: java
 permalink: index.html
 toc: false
 summary: >
-    Welcome to the documentation index for PMD and CPD! This page exposes
-    the contents of the documentation site thematically, which you can further
-    scope down using the blue filter buttons. To navigate the site, you may also use
-    the search bar in the top right, or the sidebar on the left.
+    Welcome to the documentation site for PMD and CPD! <br/><br/>
+
+
 last_updated: August 2017
 author: Jeff Jensen <jjensen@apache.org>, Andreas Dangel <andreas.dangel@adangel.org>,
         Clément Fournier <clement.fournier76@gmail.com>
@@ -15,15 +14,56 @@ author: Jeff Jensen <jjensen@apache.org>, Andreas Dangel <andreas.dangel@adangel
 
 
 
-<br/>
-
-
 {% unless site.output == "pdf" %}
 <script src="js/jquery.shuffle.min.js"></script>
 <script src="js/jquery.ba-throttle-debounce.min.js"></script>
+
+{% include custom/panel_scroll.html %}
 {% endunless %}
 
 
+## Overview
+
+<!--  You can link to an individual panel, the id is determined from the title of the panel -->
+<!--  See custom/shuffle_panel.html for the details -->
+
+**PMD** is a static source code analyzer. It finds common programming flaws like
+unused variables, empty catch blocks, unnecessary object creation, and
+so forth. It's mainly concerned with **Java and Apex**, but **supports six other
+languages**.
+
+PMD features many **built-in checks** (in PMD lingo, *rules*), which are documented
+for each language in our [Rule references](#shuffle-panel-rule-references). We
+also support an extensive API to [**write your own rules**](#shuffle-panel-writing-rules),
+which you can do either in Java or as a self-contained XPath query.
+
+PMD is most useful when **integrated into your build process**. It can then be
+used as a quality gate, to enforce a coding standard for your codebase. PMD
+can be used:
+* As a [Maven goal](pmd_userdocs_tools_maven.html)
+* As an [Ant task](pmd_userdocs_tools_ant.html)
+* As a [Gradle task](https://docs.gradle.org/current/userguide/pmd_plugin.html)
+* From [command-line](pmd_userdocs_installation.html#running-pmd-via-command-line)
+
+**CPD**, the **copy-paste detector**, is also distributed with PMD. You can also use it
+in a variety of ways, which are [documented here](pmd_userdocs_cpd.html).
+
+## Download
+
+The latest release of PMD can be downloaded from our [Github releases page](https://github.com/pmd/pmd/releases/latest).
+
+
+## Documentation
+
+The rest of this page exposes the contents of the documentation site thematically,
+which you can further scope down using the blue filter buttons. To navigate the site,
+you may also use the search bar in the top right, or the sidebar on the left.
+
+
+<br/>
+
+
+
 
 <div class="filter-options" id='grid-rule' >
       <button class="btn btn-primary" data-group="all">All</button>
@@ -40,59 +80,59 @@ author: Jeff Jensen <jjensen@apache.org>, Andreas Dangel <andreas.dangel@adangel
 
 <!--  TODO the "getting started" panel is not that useful. It would be better to make a page series. -->
     {% include custom/shuffle_panel.html
+       title="Getting started"
        tags="getting_started"
        datagroups='["getting_started"]'
-       description="These pages summarize the gist of PMD usage to get you started quickly."
-       title="Getting started" %}
+       description="These pages summarize the gist of PMD usage to get you started quickly." %}
 
 
     {% include custom/shuffle_panel.html
+       title="Rule references"
        tags="rule_references"
        datagroups='["userdocs"]'
-       title="Rule references"
        description="Pick your language to find out about the rule it supports."
        image="fa-database"
        titlemaker="page.language_name" %}
 
     {% include custom/shuffle_panel.html
+       title="Writing rules"
        tags="userdocs,extending"
        datagroups='["userdocs", "extending", "contributing"]'
-       title="Writing rules"
        description="These pages document the process of writing and testing custom rules and metrics for PMD."
     %}
 
     {% include custom/shuffle_panel.html
+       title="Usage and configuration"
        tags="userdocs"
        except_tags="extending,tools"
        datagroups='["userdocs"]'
        image="fa-cog"
-       title="Usage and configuration"
        description="Learn how to build effective and versatile rulesets."
     %}
 
 
     {% include custom/shuffle_panel.html
+       title="Contributing"
        tags="devdocs"
        except_tags="extending"
        datagroups='["contributing"]'
        image="fa-github"
-       title="Contributing"
        description="If you'd like to help us build PMD, these topics may interest you. See you around!"
     %}
 
 
 
     {% include custom/shuffle_panel.html
+       title="Tools and integrations"
        tags="tools"
        datagroups='["userdocs"]'
-       title="Tools and integrations"
        description="These pages describe solutions that integrate PMD within your build process."
     %}
 
     {% include custom/shuffle_panel.html
+       title="Major contributions"
        tags="devdocs,extending"
        datagroups='["contributing","extending"]'
-       title="Major contributions"
        description=""
     %}