assemble/handlebars-helpers — pull request #118 by davidtheclark (2014-02-22 22:29:50+00:00)
Title: Prototyping new docs format with YAML front-matter

Following up on https://github.com/assemble/handlebars-helpers/issues/115 --

I've modified two helpers' `.md` doc files to exemplify what I proposed there and verify whether you would like to work with this format.

You can see that I added YAML front-matter that contains what I consider the "vitals" for the helper. That information could then be formatted the same way for every helper -- fed through a template -- and would be accessible for indexes. On an index page, the user could see those vitals at a glance, then click to go to the helper's page to see the full explanation and exemplification.

A couple of questions came up as I was working on this:
- Are you using the term "collection" as a category containing both objects and arrays? I just wanted to be clear on that -- I'm not sure whether that's a standard meaning in the JS world or not ...
- The original example for `{{after}}` had spaces after the commas that separate the rendered items; but the helper does not in fact output spaces, so I changed it. Was the intention to *have* spaces? That's also a way of getting at a question specific to this helper: What's the use-case for `{{after}}`? If it is just to output a human-readable comma-separated list, then I suppose it *should* have spaces after the commas -- but I was suspecting it might be for something else? -- because I can't think off the top of my head of many situations in which I'd want to output data straight into a comma-separated list within my HTML. I'm asking because I think it would be worthwhile to note some possible use-cases for helpers like `{{after}}`, which aren't as self-evident as `{{#withFirst}}`.

Well let me know what you think.