Jekyll plugin for generating Markdown collection pages from CSV/YAML/JSON records πŸ§™πŸ“–
Switch branches/tags
Clone or download
Latest commit abc9ee8 Aug 2, 2018
Failed to load latest commit information.
lib test --force Aug 2, 2018
spec test --force Aug 2, 2018
.gitignore Update .gitignore May 3, 2018
.rspec init 2.0 Mar 27, 2018
.rubocop.yml rubonarc Apr 17, 2018
.travis.yml rm tree Aug 2, 2018
Gemfile add test coverage May 6, 2018
LICENSE Create LICENSE Jul 26, 2018 [skip ci] Jul 26, 2018
pagemaster.gemspec v2.0.2 [skip ci] Aug 2, 2018


Gem Version License Build Status

Maintainability Test Coverage

jekyll plugin for generating markdown collection pages from .csv, .json, or .yml records


pagemaster takes a specified .yml, .csv, or .json file from your _data folder and 'splits' each item into the front matter of an individually generated markdown page.


If you have a data set for a Jekyll collection (e.g. a CSV of page titles, image links, dates, tags, and so on), you can completely automate the generation of collection pages by running this plugin with it. And if each page in the collection uses the same custom layout, you can specify that layout in your _config.yml file and generate the look of the pages programatically.

Isn't this what Jekyll collections are for?

Kind of! pagemaster actually uses Jekyll collections, but gives you a lot more control and generates .md pages to root instead of .html pages to _site/.

Will it work with GitHub Pages?

Kind of! Because the pages are generated to root as markdown, you only need to run the plugin locally once. From there GH pages will do what it normally does with Jekyll sites: compile vanilla yaml and markdown to html. So GitHub won't run it, but it shouldn't need to.

To use

  1. Install by adding gem 'pagemaster' to the :jekyll_plugins group of your Gemfile and running $ bundle install.
  2. Add pagemaster as a plugin in _config.yml: plugins: [ pagemaster ]
  3. Set-up your collection(s) in _config.yml and add pagemaster variables. For example:
    output: true
    source: writer-list.csv
    id_key: id
    layout: writer-profile-page
    output: true
    source: scientist-survey.json
    id_key: orcid
    layout: scientist-profile-page
  1. Run $bundle exec jekyll pagemaster [collection-name], e.g. $bundle exec jekyll pagemaster writers scientists.

Note: By default, pagemaster generates hard-coded permalinks from the name of the directory and the names of the pages. If you want to skip this feature, you can run pagemaster with the --no-permalink option:

$bundle exec jekyll pagemaster --no-permalink [collection-name].


For the writers example above, pagemaster will:

  1. look for writer-list.csv in the _data directory,
  2. make a new directory called _writers, and
  3. generate a markdown page for each item in writer-list.csv, named after its id value and using the writer-profile-page.html layout.

For the scientists example above, pagemaster will:

  1. look for scientist-survey.json in the _data directory,
  2. make a new directory _scientists, and
  3. generate a markdown page for each item in scientist-survey.json, named after its orcid value and using the scientist-profile-page.html layout.
+-- _config.yml
+-- _data
|   +-- writer-list.csv
+-- _writers
|   +--
|   +--
|   +--
|   +--
|   +--
|   +-- ...
+-- _layouts
|   +-- default.html
|   +-- writer-profile-page.html
|   +-- scientist-profile-page.html
+-- _scientists
|   +--
|   +--
|   +--
|   +--
|   +--
|   +-- ..