Infusion-docs with DocPad

[Bates, Simon]

Hi all,

We have been working on converting the Fluid Infusion documentation to Markdown and moving it to GitHub:

https://github.com/fluid-project/infusion-docs

While our initial target for the documentation has been the GitHub source browser, our long term plan is to move to a static site generator so that we have control over the presentation of the documentation.

Last week I spent a bit of time exploring GitHub pages as an alternative to viewing the rendered Markdown in the GitHub browser. My investigation left me feeling like GitHub pages was not a great option. Using GitHub pages would give us a GitHub manged instance of the Jekyll site generator but no templates or styling -- we would have to implement those ourselves. This got me thinking -- if we would have to put in the work to template and style ourselves to get benefit from GitHub's Jekyll, how much work would it be to go ahead and implement a solution that is closer to our long term plan?

So, I decided to have a go at moving the documentation that we have converted so far to DocPad, a JavaScript static site generator built on Node.js. I am using Foundation for the layout and Highlight.js for syntax highlighting (minimal styling has been done beyond the defaults). The result is in GitHub and I have included instructions in the README.md on how to run DocPad locally so that you can try it out:

https://github.com/simonbates/infusion-docs-docpad

I would like to propose that we go ahead and move to DocPad and I would like to get input on what others think of this option?

Here are some observations and thoughts:

* the documentation is in src/documents (DocPad default but configurable)
* unprocessed files (CSS, JS, images) are in src/files (DocPad default but configurable)
* I am imagining that we would set up a nightly build to run DocPad and upload the generated HTML to a web server (either one we manage, or it could be GitHub pages)
* before we make the pages public, we would need to do some templating and styling work
* DocPad uses file name extensions to specify what processing should be done on each file and this results in the documents having names such as IoCSS.html.md (meaning convert from Markdown to HTML); this could be a little clunky and it is possible to rely on some defaults handling and name the documents without the ".html", such as IoCSS.md
* when serving the pages from GitHub, we link to the Markdown file, such as IoCSS.md; switching to DocPad would require us to change our link targets to the generated HTML file names, such as IoCSS.html (I am investigating this now to see if there is any special link handling that might be useful here)

Please have a look at the DocPad version of the docs and let me know what your thoughts are.

Thanks,
Simon