Infusion-docs with DocPad

[Colin Clark]

Hi Simon,

Thanks for such a clear summary of the approach. As Tony mentioned, I’m glad we started with GFM so that it was easy to get up and running with just the built-in Github source preview while we were still wrangling with options for static site generators. The DocPad version of the documentation looks great, and it looks like it will be pretty straightforward to style the documentation consistently with the designs for a new Fluid Project website.

I think your proposal to use DocPad seems quite reasonable. I can’t say I like the idea of using file extensions to control the flow of template parsing in DocPad, but it sounds like there should be some viable ways to avoid this as much as possible. In the long run, I hope that we will be able to introduce Infusion and the new Renderer into the work flow (not for a year or two, realistically), so wherever we can minimize hard dependencies on a templating strategy, we should.

I agree with your approach and am looking forward to your idea of setting up a nightly build for our documentation.

+1

Colin

On May 26, 2014, at 4:10 PM, Bates, Simon <sbates at ocadu.ca> wrote:

> 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
> _______________________________________________________
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work