orgsync/orgsync-api-java — pull request #18 by justinsteffy (2014-07-31 19:44:36+00:00)
Title: Create the website using JBake

This didn't turn out as easily as I would have hoped. It doesn't appear there are any good options for a static site that also handles versioning. So instead, I've come up with a solution using [`JBake`](http://jbake.org) (via the [gradle plugin](https://github.com/jbake-org/jbake-gradle-plugin)) and a healthy dose of gradle/groovy.

Almost all of the build logic lives in `site.gradle`, so at least its contained. There are a few features JBake doesn't provide which led to this design, this bigest of which is it doesn't allow templates in the `content` directory. So instead, I use this layout:

* `site` - the main directory for all site-related markup
* `assets` - The assets that are copied over via JBake
* `docs` - The raw docs without any JBake specific front matter
* `pages` - Some `pages` (in JBake speak), but as templates, so I can pass versions in.
* `templates` - The standard JBake templates directory

First, I use the `type` of `page` for the documentation and downloads pages. Each of these are templates that take the current version and a list of older versions to provide links to. For the documentation pages, I use the `type` of `post`, and add some extra metadata to the front matter. There is also a `Contents` index page that is made dynamically for the docs (which should probably be a `page` template, but for now is just in code).

All docs/downloads are set up to be relatively linked under a `version/$version/` url. This allows the `docs` markdown to not need to know its current version (e.g. to link to the javadoc). Otherwise, all the docs markdown would have to be templates also.... which is doable.

Here are the steps that are taken in the build:

* `copySite` - Copy the `site` to `build/site` where we will put the files that JBake will bake
* `convertPages` - Take each `.gsp` template from `pages` and render it into the `content` dir
* `convertDocs` - Take each markdown file in `docs` and add appropriate JBake front matter
* Find each doc in sorted order and keep this info in an array
* Convert each doc and include some front matter about the next and previous links
* Dynamically build a `Contents` index page as markdown
* Copy all of these into `versions/$version` under `content`
* `copyJavadoc` - the `javadoc` task is run and its output is placed under `assets/version/$version/javadoc`
* We have to put it in `assets` so that its copied over as-is.
* `copyDist` - Create the distribution zip and place it in `assets/versions/$version/` so its copied over

Most of the site/styling/js is just from the standard JBake template... so it needs some help.

Also, the `jbake` task now depends on the tasks above so they all happen before, so `./gradlew jbake` is how you get the site built into `build/jbaked`.