Skip to content

Article Order

Jump to bottom
Andrea Campi edited this page Oct 21, 2012 · 9 revisions

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 tag in your <head>.

    <link rel="index" href="..." type="application/json">

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 contents property. The following example shows nesting of articles to an arbitrary depth.

[
  {
    "url": "section-1.html",
    "contents": [
      {
        "url": "article-1.1.html"
      },
      {
        "url": "article-1.2.html"
      }
    ]
  },
  {
    "url": "section-2.html",
    "contents": [
      {
        "url": "sub-section-2.1.html",
        "contents": [
          {
            "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"
  }
]
Clone this wiki locally