Working with Jekyll
Bring the power of GraphQL to any static site use-case. This doc will show you the process for integrating your GraphQL API project with a Jekyll build.
But be forewarned: If you're deploying your site to Github Pages, you'll have to build it yourself rather than letting Github build for you. This is because you need a GraphQL plugin to integrate your project, and Github only allows a curated list of Jekyll plugins to run in build processes on their servers.
Luckily, there is a standard process for building your own site and deploying the generated files to Github Pages. To learn more, check out Github's docs on integrating Jekyll with Github pages.
Follow along with this guide by checking out our starter project repo. Our starters let you instantly deploy a pre-configured project.
Setting up Jekyll
First you'll need to install Ruby on your machine. For that, you'll have to go to the official Ruby website and follow their instructions for installing it on your operating system. Once Ruby is installed, you'll need the RubyGems package manager. Check out the official website for instructions.
Finally, if you have Ruby and RubyGems already installed, you'll need to install the two packages you'll be using to generate your site: jekyll and bundler. Run the following command in your console:
gem install bundler
Now, in a directory where you keep your projects, open the console and create a new jekyll project with the following command:
jekyll new your-project-name-here
Now you're all set to connect to your project.
If you're running version 3.x or higher of Ruby, you may have issues executing jekyll commands in the console. This is because jekyll depends on webrick, which is no longer packaged with Ruby versions beyond 2.7.x. Add webrick to your project to solve this problem.
bundle add webrick
Connecting your project
To connect to your project, you need your API Endpoint and an API key.
If you haven't created a project yet, follow this guide to do so.
If you already have a project, your API Endpoint will be in the admin UI. In the home tab, look for the "Useful Snippets" section.
Copy the API Endpoint and save it somewhere secure.
To get an API Key, you'll have to create one. Read our docs on creating an API Key here.
Adding the jeql plugin
Next you'll need a plugin to make GraphQL queries during your jekyll build process.
There is no official GraphQL Jekyll plugin, but there are two popular open-source options:
- jeql - A plugin made specifically for consuming GraphQL APIs in your Jekyll build process.
- GQLi - A more general ruby gem for consuming GraphQL APIs that is not specifically made for Jekyll.
For this example, we'll be using jeql.
To add jeql to your build process, make sure you're in your jekyll project when you open the console. Enter the following command:
gem jeql
Now open your jekyll config file, _config.yml. You'll find a plugins section near the top. Here you'll tell jekyll to run jeql.
# Build settings
plugins:
- jeql
Now you'll need to define jeql for your config file — but you shouldn't expose your API Endpoint and API Key to the public.
The solution is to create a second config file, which we'll call _config2.yml. In your .gitignore file, add _config2.yml to its own line.
_site
.sass-cache
.jekyll-cache
.jekyll-metadata
vendor
_config2.yml
Now let's open _config2.yml and add the following code:
jeql:
graphqlapi:
url: "Your-Endpoint-Here"
header:
Authorization: "Bearer Your-Api-Key-Here"
In the above code, we define graphqlapi as an endpoint for jeql to recognize. We set the url to our API Endpoint, and we add authorization to the header. The GraphQL API Endpoints require a Bearer Token authorization that takes your API Key as the token.
To define queries for jeql to run in your project's GraphQL API, you must create a folder called _graphql. Inside this folder, you'll create a json file that stores your query as a json object. For this example, we'll create a query that requests a list of all products, as well as their names and prices, from an ecommerce backend:
{
"query":" query{ getProductList{ items{ name price } } }"
}
Now you just have to reference the query in your markdown templates. For example, let's put our product list and details in the index.markdown file.
---
layout: home
---
<ul>
{% graphql endpoint: "graphqlapi", query: "getProductList" %}
{% for product in data["getProductList"]["items"] %}
<li>
{{product["name"]}} Price:
<em>{{product["price"]}}</em>
</li>
{% endfor %}
{% endgraphql %}
</ul>
{% graphql endpoint: "graphqlapi", query: "getProductList" %}
{% for product in data["getProductList"]["items"] %}
{{product["name"]}} Price: {{product["price"]}}
{% endfor %} {% endgraphql %}
The above code hits the endpoint you defined in your _config2.yml file as graphqlapi, which will be your API Endpoint. It then executes the query in the file getProductList.json in the _graphql folder. Finally, it returns the data object contained in the response it gets from your project's API Endpoint.
For this example, the response object would look something like data.getProductList.items, where items is an array of objects containing the name and price of each product in our ecommerce backend.
To access this data, in Jekyll's templating language, we have to index each property as demonstrated above.
To learn more about Jekyll's templating language, check out Jekyll's docs on the subject.
Building your site
Finally you're ready to build.
You'll use the bundle gem to build or serve your jekyll site. To do so, you must set a --config flag to specify the two config files you'll be using, and which order you want to run them in. For our example, you would build your site with the following command:
bundle exec jekyll build --config _config.yml,_config2.yml
In the above command, we're telling jekyll to build based on the settings laid out in _config.yml and _config2.yml, in that order. Note that you cannot put a space after the comma denoting the two commands.
To learn more about Jekyll config files, check out their docs on the subject.
To serve your site locally, you'll execute a similar command, substituting serve for build:
bundle exec jekyll serve --config _config.yml,_config2.yml
Here's what the final page might look like for you:
Deploying your site
Normally, we don't offer any opinion on where and how you should deploy your static site; however, Jekyll is a special case. Many choose Jekyll because of how smoothly it integrates with Github Pages.
Though jeql is not elibile for Github's automated build process, you can deploy your site to Github pages, or any static host, by building it locally first.
Read the Jekyll docs to learn more about integrating Jekyll with Github Pages
If you'd rather deploy on Netlify, here's their official guide on that process.
Still need help? Get in touch with us.