laurenancona / jekyll-datapage_gen

Generate one page per yaml record in Jekyll sites.

Jekyll Data Pages Generator

Jekyll allows data to be specified in YAML or JSON format in the _data dir.

If the data is an array, it is straightforward to build an index page, containing all records, using a Liquid for loop. In some occasions, however, you also want to generate one page per record. Consider, e.g., a list of team members, for which you want to generate an individual page for each member.

This generator allows one to specify data files for which we want to generate one page per record.

Among the advantages:

• general purpose: it works with any array of data: people, projects, events, … you name it
• it manages multiple data sources in the same website

Installation

Download data_page_generator.rb and put it in the _plugins directory of your website.

Usage

• Specify in _config.yml the data files for which you want individual page to be generated.
• Launch Jekyll

The specification in config.yml is as follows:

page_gen:
  - data: <<name of the data>>
    template: <<name of the template to use to generate the page>>
    name: <<field used to generate the filename>>
    dir: <<directory in which files are to be generated>>
    extension: <<extension used to generate the filename>>
  - ...

where:

data

is the name of the file to read

name

is the name of a field which contains a unique identifier that can be used to generate a filename

template

is the name of a template to generate the pages (it defaults to the value of data + “.html”). Optional: if not set, the generator uses the value of the data field

dir

is the directory where pages are generated (it defaults to the value of data). Optional, if not specified, the generator uses the value of the data field.

extension

is the extension of the generated file (it defaults to the “html” extension). Optional, if not specified, the generator uses “html” extension.

More than one data source can be specified: the generator iterates over each element of the data_gen array.

A liquid tag is also made available to generate a link to a given page. For instance:

   {{ page_name | datapage_url: dir }}

generates a link to page_name in dir.

Named Folders

By default the plugin generates one filename per record. If you prefer to generate named folders, set the page_gen-dirs to true in config.yml.

Example

1. You have an member.yml file stored in the _data directory of your Jekyll website, with the following content:

- name: adolfo villafiorita
  bio: long bio goes here
- name: pietro molini
  bio: another long bio
- name: aaron ciaghi
  bio: another very long bio

Alternatively, you could have member.json file stored in the _data directory with the following content and the example would work the same:

[

  {

    “name”: “adolfo villafiorita”,

    “bio”: “long bio goes here”

  },

  {

    “name”: “pietro molini”,

    “bio”: “another long bio”

  },

  {

    “name”: “aaron ciaghi”,

    “bio”: “another very long bio”

  }

]

2. There is a profile.html file stored in the _layouts directory:

<h1>{{page.name}}</h1>

{{page.bio}}

3. _config.yml contains the following:

page_gen:
  - data: 'member'
    template: 'profile'
    name: 'name'
    dir: 'people'

Then, when building the site, this generator will create a directory people containing, for each record in member.yml, a file with the record data formatted according to the profile.html layout. The record used to generate the filename of each page is name.

$ cd example
$ jekyll build
$ cat _site/people/adolfo_villafiorita.html
<h1>Adolfo Villafiorita</h1>

long bio goes here

Check the example directory for a live demo. (Notice that the ruby file in _plugins is a symbolic link; you might have to remove the link and manually copy the ruby file in the _plugins directory, if symbolic links do not work in your system.)

Compatibility

Tested with Jekyll 3.1.6, it should also work with previous versions of Jekyll. Try with the included example and open an issue if you find any compatibility issue.

Author

Adolfo Villafiorita

Known Bugs

No known bugs; unknown number of unknown bugs.

License

Distributed under the terms of the MIT License