mojombo/jekyll — pull request #1003 by liufengyun (2013-04-27 15:01:45+00:00)
Title: support data sources

Data Source enables you to load data from external sources, such as web, file system,
databases and then use them inside views.

Jekyll supports two built-in data sources:

- `YAML` from local file system
- `JSON` from web

And it's easy to roll your own data source driver.

### JSON

In ordre to use json from web in your site, set following in `_config.yml` file:

``` yaml
data_sources:
- name: albums # will be used as site.albums to access data, no spaces allowed
type: json
url: http://www.example.com/albums.json # must be http or https
```

Then, inside html you can access the data as following:

{% for album in site.albums %}
...
{% endfor %}

### YAML

To define a yaml data source, set following in `_config.yml` file:

``` yaml
data_sources:
- name: products # will be used as site.products to access data, no spaces allowed
type: yaml
path: _data/products.yml # must be on local file system
```

Then, inside html you can access the data as following:

{% for product in site.products %}
...
{% endfor %}

### Custom drivers

The skeleton of your driver should be as follows:

``` ruby
module Jekyll
module Drivers
class XxxDriver
# source options are passed in as an Hash
def initialize(options)
end

# return the loaded data as Array or Hash or a nested structure of Array and Hash
def load
end
end
end
end
```

After you've implemented the code, put the source file inside `_plugins` directory.

Then in `_config.yml`, you can use the driver as follows:

``` yaml
data_sources:
- name: students
type: xxx
```

If the type is `xxx`, Jekyll assumes the corresponding driver is `Jekyll::Drivers::XxxDriver`. If the type is `xxx_yyy`, the driver should be `Jekyll::Drivers::XxxYyyDriver`, and so on.

Beside the obligatory `name` and `type` options, you can define any more options to be used inside the driver.