bramstein/Treesaver TOC

## Treesaver TOC
A Treesaver document can contain one or more individual articles:

  <body>
    <article id="first">
    </article>
    <article id="second">
    </article>
  </body>

These articles will be shown in the order they are declared in. Articles can link to other articles by identifier. So in the above example, the first article can link to the second one with `<a href="#second">...</a>`.

If you want a more advanced Table Of Contents, you will need to declare your publication structure in a JSON file. This JSON file should be linked to from each individual HTML document through a `<link rel="index" href="..." type="application/json">` tag. The basic structure of the linked to JSON file is very simple:

  [
    {
      "url": "article-1.html"
    },
    {
      "url": "article-2.html"
    }
  ]

Each `url` points to a HTML document, which *should* contain a single article. Using the JSON file above, Treesaver will display the articles in order `article-1.html`, `article-2.html`. It is also possible to define a hierarchical structure for your documents using the "children" property. The following example shows nesting of articles to an arbitrary depth.

  [
    {
      "url": "section-1.html",
      "children": [
        {
          "url": "article-1.1.html"
        },
        {
          "url": "article-1.2.html"
        }
      ]
    },
    {
      "url": "section-2.html",
      "children": [
        {
          "url": "sub-section-2.1.html",
          "children": [
            {
              "url": "article-2.1.1.html"
            },
            {
              "url": "article-2.1.2.html"
            }
          ]
        },
        {
          "url": "article-2.2.html"
        }
      ]
    }
  ]

When Treesaver parses this JSON file it will determine the article order by flattening the hierarchy. The resulting article order will be: `section-1.html`, `article-1.1.html`, `article-1.2.html`, `section-2.html`, `sub-section-2.1.html`, `article-2.1.1.html`, `article-2.1.2.html`, and `article-2.2.html`.

So what happens when you accidentally include more than `<article>` in a document linked to by the JSON TOC index? For example, what if the HTML document `article-1.2.html` actually had two `<article>` elements:

  <body>
    <article>
      <h1>Article 1.2</h2>
    </article>
    <article id="notes">
      <h1>Some notes</h1>
    </article>
  </body>

Treesaver will try to do the correct thing and insert the article after `article-1.2.html` and before `section-2.html`. You could also link to the second article if it has an identifier (which it does in this case) by `<a href="article-1.2.html#notes">...</a>`. This works, but it is highly recommended to use one HTML document per article when working with a Table Of Contents index.

Meta-data
---------
Each entry in the Table Of Contents can have its own meta-data, which will be supplied to the Chrome, to (for example) render in a sidebar. Suppose that we would like to have title and author meta-data in our sidebar. We simply add new properties in the Table Of Contents file:
  [
    {
      "url": "article-1.html",
      "title": "Article One",
      "author": "John Doe"
    },
    {
      "url": "article-2.html",
      "title": "Article Two",
      "author": "Jane Doe"
    }
  ]
	A Treesaver document can contain one or more individual articles:

	<body>
	<article id="first">
	</article>
	<article id="second">
	</article>
	</body>

	These articles will be shown in the order they are declared in. Articles can link to other articles by identifier. So in the above example, the first article can link to the second one with `<a href="#second">...</a>`.

	If you want a more advanced Table Of Contents, you will need to declare your publication structure in a JSON file. This JSON file should be linked to from each individual HTML document through a `<link rel="index" href="..." type="application/json">` tag. The basic structure of the linked to JSON file is very simple:

	[
	{
	"url": "article-1.html"
	},
	{
	"url": "article-2.html"
	}
	]

	Each `url` points to a HTML document, which should contain a single article. Using the JSON file above, Treesaver will display the articles in order `article-1.html`, `article-2.html`. It is also possible to define a hierarchical structure for your documents using the "children" property. The following example shows nesting of articles to an arbitrary depth.

	[
	{
	"url": "section-1.html",
	"children": [
	{
	"url": "article-1.1.html"
	},
	{
	"url": "article-1.2.html"
	}
	]
	},
	{
	"url": "section-2.html",
	"children": [
	{
	"url": "sub-section-2.1.html",
	"children": [
	{
	"url": "article-2.1.1.html"
	},
	{
	"url": "article-2.1.2.html"
	}
	]
	},
	{
	"url": "article-2.2.html"
	}
	]
	}
	]

	When Treesaver parses this JSON file it will determine the article order by flattening the hierarchy. The resulting article order will be: `section-1.html`, `article-1.1.html`, `article-1.2.html`, `section-2.html`, `sub-section-2.1.html`, `article-2.1.1.html`, `article-2.1.2.html`, and `article-2.2.html`.

	So what happens when you accidentally include more than `<article>` in a document linked to by the JSON TOC index? For example, what if the HTML document `article-1.2.html` actually had two `<article>` elements:

	<body>
	<article>
	<h1>Article 1.2</h2>
	</article>
	<article id="notes">
	<h1>Some notes</h1>
	</article>
	</body>

	Treesaver will try to do the correct thing and insert the article after `article-1.2.html` and before `section-2.html`. You could also link to the second article if it has an identifier (which it does in this case) by `<a href="article-1.2.html#notes">...</a>`. This works, but it is highly recommended to use one HTML document per article when working with a Table Of Contents index.

	Meta-data
	---------
	Each entry in the Table Of Contents can have its own meta-data, which will be supplied to the Chrome, to (for example) render in a sidebar. Suppose that we would like to have title and author meta-data in our sidebar. We simply add new properties in the Table Of Contents file:
	[
	{
	"url": "article-1.html",
	"title": "Article One",
	"author": "John Doe"
	},
	{
	"url": "article-2.html",
	"title": "Article Two",
	"author": "Jane Doe"
	}
	]