jeql is a GraphQL plugin for jekyll
Switch branches/tags
Nothing to show
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin initial commit Mar 28, 2018
lib bump version again Apr 3, 2018
spec make code more resilient Apr 2, 2018
.gitignore initial commit Mar 28, 2018
.rspec initial commit Mar 28, 2018
.travis.yml initial commit Mar 28, 2018 initial commit Mar 28, 2018
Gemfile initial commit Mar 28, 2018
Gemfile.lock bump version again Apr 3, 2018
LICENSE.txt initial commit Mar 28, 2018 add rubygems version to README Apr 3, 2018
Rakefile initial commit Mar 28, 2018
jeql.gemspec fix gem host Apr 3, 2018

jeql Build Status Gem Version


Add this to to your site's Gemfile:

gem 'jeql'

Add the following to your site's config file (usually _config.yml):

  - jeql

After this run bundle install within your site's directory.


GraphQL endpoints

You need to define graphQL endpoints within your jekyll config. Within the key jeql list all your providers in the format:


An example config to access the graphQL - API from github would look like this:

    url: ""
      Authorization: "bearer my-secret-header"

Attention: Make sure to not commit authorization tokens in a public repository. Instead make use of jekyll's multiple-config-file feature and add these tokens to a private config file which is not checked into your version control system.

GraphQL queries

Queries in jeql are specified as json files and live within the _jeql directory of your jekyll site. An example query file would have the following content:

  "query": "query { viewer { name repositories(last: 3){ nodes { name }} }}"

and would e.g. be stored as /_jeql/last_touched_repositories.json.

Using it in liquid

After all this setup has been done you can now use the graphql block tag in your template files. The graphql tag expects two parameters:

  • endpoint
  • query

endpoint is the name of the graphQL - API endpoint as you have it defined in your jekyll config file. query is the name of the file under _jeql in which you stored the graphQL query that should be executed against the endpoint (withou the .json extension).

An example which uses the settings and query from the paragraphs above would look like this:

{% graphql endpoint: "github", query: "last_touched_repositories" %}
{% endgraphql %}

Between the opening and closing graphql tag you have access to the variable data which will contain the response of the graphQL query:

{% graphql endpoint: "github", query: "last_touched_repositories" %}
  {% for repo in data["viewer"]["repositories"]["nodes"] %}
  {% endfor %}
{% endgraphql %}


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the jeql project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.


This gem was inspired by github-metadata and jekyll-seo-tag.