Add some METADATA files to control docs layout.

site/dev/tools/markdown.md

 Markdown
 ========
 
 This site can handle normal MarkDown and many common extensions. To learn
 how the following is done please see the [source for this page](./markdown.md).
 Any file you put under `/site/` that has the extension `.md` will be processed
 as MarkDown. All other files will be served directly. For example, images
 can be added and they will be served correctly and referenced from within MarkDown files.
 
 When preparing for a code review of site docs you can get a preview of how the
@@ skipping 16 matching lines @@
 Then visit http://localhost:8000 to preview your changes. There is no need to
 restart the server for file changes, but you will need to restart it if there
 are changes to the navigation menu, i.e. you add or remove a file and want it
 to appear in the navigation on the right hand side of the page.
 
 If port 8000 is unavailable on your machine you can set the port to use via
 the --port flag:
 
     docserver --preview --port=:8002
 
+METADATA
+--------
+
+By default all files and directories that appear in the same level are sorted
+alphabetically in the navigation menu, with files appearing before

[hcm, 2015/03/05 14:38:30]

"sorted alphabetically by filename..." which I think you call out later, but
maybe add that nuance here.  This confused me at first when seeing the titled
pages not appearing to be alphabetically sorted.

[jcgregorio, 2015/03/05 15:10:02]

Done.

+directories. You can override this default behavior by adding a METADATA file
+to a directory. A METADATA file is a JSON file of the following format:
+
+~~~~
+   {
+     "dirOrder": ["sample", "quick", "special"],
+     "fileOrder": ["download", "api"]
+   }
+~~~~
+
+If a file or directory doesn't appear in `dirOrder` or `fileOrder` then it is sorted
+to appear after the members of `dirOrder` or `fileOrder` respectively. All
+files and directories that aren't controlled by a METADATA file are sorted in
+alphabetical order by their filename.
 
 Some Example MarkDown
 ---------------------
 
 This is a [link](https://www.google.com). You can also create
 ordered and unordered lists:
 
 1. First
 2. Second:
   * Fee
@@ skipping 345 matching lines @@
 
 Output:
 
     <p>If you want your page to validate under XHTML 1.0 Strict,
     you've got to put paragraph tags in your blockquotes:</p>
     
     <pre><code>&lt;blockquote&gt;
         &lt;p&gt;For example.&lt;/p&gt;
     &lt;/blockquote&gt;
     </code></pre>