Infusion-docs with DocPad

Thu May 29 13:25:22 UTC 2014

Hi Simon,

Have you any thoughts on Stylus (the default CSS pre-processor that comes
with Docpad)? Justin and I have been having off-and-on discussions about
moving forward with choosing a pre-processor for Infusion work, so any
notes you may have would be helpful.

Will markdown be sufficient for our documentation needs, or will we expect
to mix in HTML as well? i.e. If you want to apply special styles or
formatting (i.e. you want to have an image floated left and text to the
right) you will have to revert to doing HTML.

Here's an interesting tip on using Docpad (not related to the Infusion
docs) - you can chain extensions on a file to execute processing multiple
times - i.e. IoCSS.html.eco.eco.md

This is particularly handy in cases where an eco template has a query that
returns an eco template fragment which then needs to be converted to HTML.
If a single .eco extension, we will only see the eco fragment in the HTML,
but with a second eco extension, that eco fragment gets converted into HTML.

There may be a more proper way of doing this, but it was the only way I
discovered to process eco templates that were 2 levels deep.

On Mon, 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
>

-- 

*JONATHAN HUNG*

INCLUSIVE DESIGNER, IDRC

*T:* 416 977 6000 x3951

*F:* 416 977 9844

*E:* jhung at ocadu.ca

*OCAD UNIVERSITY*

Inclusive Design Research Centre

205 Richmond Street W, Toronto, ON, M5V 1V3

www.ocadu.ca

www.idrc.ocad.ca
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20140529/7ea8383e/attachment.htm>