Add advanced usage and TOC

.gitignore

@@ -1,3 +1,4 @@
 work/
 target/
 .idea
+.DS_Store

docs/advanced.md

@@ -0,0 +1,30 @@
+Advanced Usage
+==============
+
+In addition to Unit and Coverage results, this plugin supports two additional features
+you may want to take use of.
+
+Custom Comments
+---------------
+
+If you'd like to post additional text back to Phabricator, you can add text to the `.phabricator-comment` file
+(you can change the name of the file in your job configuration page):
+
+![Comment Configuration](/docs/custom-comment.png)
+
+Any text present in this file will be echoed verbatim to the comment that Jenkins posts back to
+Phabricator. If you'd like to preserve formatting, check the "Preserve Formatting" block and the
+plugin will surround the comment in triple-backticks (```)
+
+Custom Lint
+-----------
+
+If you'd like to send Lint Violations as well, you can echo Harbormaster-compatible JSON
+(where each line is a valid JSON dictionary) into the `.phabricator-lint` file.
+
+Note that the file as a whole is **not valid JSON** (e.g. if you call
+`JSON.parse('.phabricator-lint')`) it will fail. This is a design decision to make it easy for build
+scripts to `tee` (echo line-by-line) violations without having to produce well-formed JSON,
+which requires knowing upfront how many violations are present.
+
+![Lint Configuration](/docs/custom-lint.png)

readme.md

@@ -7,6 +7,20 @@ if Harbormaster is not enabled).
 [Phabricator]: http://phabricator.org/
 [Jenkins]: https://jenkins-ci.org/
 
+Table of Contents
+=================
+* [Configuration](#configuration)
+  * [Phabricator Configuration](#phabricator-configuration)
+  * [Jenkins Setup](#jenkins-setup)
+* [Usage](#usage)
+  * [Jenkins Job](#jenkins-job)
+  * [Harbormaster](#harbormaster)
+  * [Herald](#herald)
+* [Advanced Usage](docs/advanced.md)
+* [Test Your Configuration](#test-your-configuration)
+* [Development](#development)
+* [Testing](#testing)
+
 Configuration
 =============
 
@@ -56,7 +70,7 @@ Jenkins Job
   1. Navigate to the **Post-build Actions** section.
   2. Click the **Add post-build action** button and select **Post to Phabricator**.
   3. Make sure the **Comment on Success** and **Comment with console link on Failure** checkboxes are selected.
-  4. Optionally: 
+  4. Optionally:
     1. If you have [Uberalls](https://github.com/uber/uberalls) enabled, enter a path to scan for Cobertura reports.
     2. If you want to post additional text to Phabricator other than "Pass" and "Fail", select the **Add Custom Comment** checkbox. Then create a `.phabricator-comment` file and enter the text you want Jenkins to add to the build status comment in Phabricator.
 ![Add post-build action](/docs/configure-job-post-build.png)
@@ -75,9 +89,9 @@ With Phabricator, Jenkins, and your Jenkins jobs configured it's time to configu
 7. Use this template URI to fill in the URI field for the build plan: `https://ci.example.com/buildByToken/buildWithParameters?job=test-example&DIFF_ID=${buildable.diff}&PHID=${target.phid}`
 
 	Be sure to replace `https://ci.example.com` with the URI of your Jenkins instance and `test-example` with the name of your Jenkins job.
-	
+
 	If your Jenkins instance is exposed to the internet, make sure to install the [Build Token Root Plugin][] and fill in the `token` parameter.
-	
+
 [Build Token Root Plugin]: https://wiki.jenkins-ci.org/display/JENKINS/Build+Token+Root+Plugin
 
 8. Click the **When Complete** dropdown menu and select **Wait For Message**.
@@ -110,6 +124,12 @@ commenting on your diff:
 
 ![Example](/docs/uberalls-integration.png)
 
+Advanced Usage
+--------------
+
+Now that you have build status and optionally coverage data set up, check out some
+[advanced features](docs/advanced.md).
+
 Development
 -----------