playframework/playframework — pull request #2542 by jroper (2014-09-05 22:48:52+00:00)
Title: Improve sidebar menus in documentation

From @jroper (followup to Issue #2513)

What would really be awesome, and we've been thinking about this a bit of recent, is to implement some sort of automatic way to generate the sidebars and table of contents and add that to play-doc, we've talked about this for a while. I think the current approach of having _Sidebar.md is just not that good.

I'd imagine something like this: each folder contains maybe a _toc.json (or yaml or whatever) file which describes the order in which all the files/folders in there appear in its table of contents. It might look like this:
```
{
"title": "Home",
"page": "Home.md",
"toc": [
{ "dir": "gettingStarted" },
{ "dir": "javaGuide", "depth": 0 },
{ "dir": "scalaGuide", "depth": 0 }
]
}
```
By default, when rendering a directory item, it will descend into the directory and render a sub list for its children. If a depth is specified, then it will only go that deep into the directory. The title will be read from the toc title in that directory, but can be overridden. The page attribute is optional, if present, when the title of that particular toc is rendered, it will link to the given page.

Then we can have a _sidebar.json which describes what should be in the sidebar, when rendering the sidebar you would look in the directory of the current page, then in the parent, and so on (the same way the current mechanism works). This might look something like this:
```
{
"sidebar": [
{ "toc": "." },
{ "toc": "/manual/javaGuide/main" },
{ "toc": "/manual/detailedTopics" },
{ "toc": "/manual/javaGuide/advanced" },
{ "toc": "/manual/javaGuide/tutorials" }
]
}
```
This will probably suffice for now, we could also add the ability to render custom sections with particular pages, define a custom title, etc, but I don't think that's needed just yet. The tocs above would of course render at a depth of 1 because it's the sidebar.

So, given this, what we'd then need would be two new pegdown plugins added to the play-doc project. The first is a toc plugin that renders a toc. @toc@ might be an appropriate syntax.

The second is a next page plugin that renders a link to the next page, according to the table of contents.

The above would also really facilitate generating a PDF of our docs, as we could use the main toc as a way to get every page rendered in the right order (with of course a toc in the PDF) - in fact it would be trivial to write a pegdown serialiser that output LaTeX, and then that can be very easily compiled to PDF with proper table of contents/page numbers/etc.