Mimics Jekyll _data/ directory

[adrienrn]

One thing that I like when building a documentation website is having data files – in yml, json or csv sometimes – and use those files to generate page parts. It lets me update the documentation easily from version to version of my project.

Use case / Jekyll way:

I've got a simple jQuery plugin that has some options and some events. Jekyll lets me do that by storing files in _data/. I've got two YAML files, events.yml and options.yml structured as follows:

-
    name: sheeped.jq.sheeper
    description: >
        Fired **after** a new sheep as been created and added to the herd.

        `event.target` is the new sheep added to the herd

-
    name: unsheep.jq.sheeper
    description: >
        Fired **before** a sheep is deleted.

        `event.target` is the sheep due to be deleted from the herd
...

In my documentation page, I simply do:

<table>
    <tr>
        <th>Event</th>
        <th>Description</th>
    </tr>
    {% for event in site.data.events %}
        <tr>
            <td>
                <span class="docs-highlight">{{ event.name }}</span>
            </td>
            <td>{{ event.description|markdownify }}</td>
        </tr>
    {% endfor %}
</table>

More details on the github of jQuery Sheeper, under docs/.

Couscous ?

Does Couscous have a feature like that ? If not, do you think it could be something you're likely to include ?

I understand that I could put those data in the couscous.yml. However, I'm afraid it would be wuickly crowded. Plus, I've got some script parsing my project to create those files or very large set of datas (sales by countries to produce a world map chloropeth for example)

If it already has, I missed it in the documentation and i'll be glad to make a pull request to document that.

[mnapoli]

You are right that right now you can put such data in couscous.yml. However, as you said, it can quickly get crowded.

I think it would make sense to allow importing other YAML files in couscous.yml, that would allow achieving what you want right?

[adrienrn]

As I see it, there's two options:

1. Import files in couscous.yml, making them available to all templates, as you said.
2. Load all files from a given directory (whose path be defined in couscous.yml; not imposing it like Jekyll to follow Couscous philosophy.

I think the first is closer to Couscous philosophy though, loading files from wherever we want and is lighter. The only downside is we would have to ask for every files manually. :)

[mnapoli]

Yes the first option is better for Couscous I think, a big PITA I found in Jekyll and similar tools is how everything is magical (aka convention). Importing each file explicitly (even if it can be a good amount of them) is better IMO.

[adrienrn]

One small addition: Jekyll is capable of loading plenty of formats: yml, json, csv.

If YAML seems obvious choice for the everyday life, plenty of tools output only json or csv. One thing that pops my mind is Google Analytics or Wordpress analytics that outputs CSV only.

[mnapoli]

Let's stay simple first: importing a config file is a good way to solve the problem at hand. Couscous in itself isn't really a data analytics tool.