Jekyll-Contentful-Data-Import is a Jekyll extension to use the Jekyll static site generator together with the API-driven Contentful CMS. It is powered by the Contentful Ruby Gem.
Experience the power of Jekyll while staying sane as a developer by letting end-users edit content in a web-based interface.
Create a Gemfile in your Jekyll project and add the following:
source 'https://rubygems.org'
group :jekyll_plugins do
gem "jekyll-contentful-data-import"
end
Then as usual, run:
bundle install
Run jekyll contentful
in your terminal. This will fetch entries for the configured
spaces and content types and put the resulting data in the
local data folder as yaml files.
The contentful
command has a --rebuild
option which will trigger a rebuild of your site
To configure the extension, add the following configuration block to Jekyll's _config.yml
:
contentful:
spaces:
- example: # Jekyll _data folder identifier - Required
space: cfexampleapi # Required
access_token: b4c0n73n7fu1 # Required
cda_query: # Optional
include: 2
limit: 100
all_entries: true # Optional - Defaults to false, only grabbing the amount set on CDA Query
all_entries_page_size: 1000 # Optional - Defaults to 1000, maximum amount of entries per CDA Request for all_entries
content_types: # Optional
cat: MyCoolMapper
client_options: # Optional
api_url: 'preview.contentful.com' # Defaults to 'api.contentful.com' which is Production
base_path: app_path # Optional - Defaults to Current directory
Parameter | Description |
---|---|
space | Contentful Space ID |
access_token | Contentful Delivery API access token |
cda_query | Hash describing query configuration. See contentful.rb for more info (look for filter options there). Note that by default only 100 entries will be fetched, this can be configured to up to 1000 entries using the limit option. |
all_entries | Boolean, if true will run multiple queries to the API until it fetches all entries for the space |
all_entries_page_size | Integer, the amount of maximum entries per CDA Request when fetching :all_entries |
content_types | Hash describing the mapping applied to entries of the imported content types |
client_options | Hash describing Contentful::Client configuration. See contentful.rb for more info. |
base_path | String with path to your Jekyll Application, defaults to current directory. Path is relative to your current location. |
You can add multiple spaces to your configuration
The extension will transform every fetched entry before storing it as a yaml file in the local data folder. If a custom mapper is not specified a default one will be used.
The default mapper will map fields, assets and linked entries.
You can create your own mappers if you need to. The only requirement for a class to behave as a
mapper is to have a map
instance method.
Following is an example of such custom mapper that adds all sys
properties to the entry:
class MySysMapper < ::Jekyll::Contentful::Mappers::Base
def map
result = super
entry.sys.each do |k, v|
name, value = map_field k, v
result['sys'][name] = value
end
result
end
end
In most cases you may want to avoid including your credentials in publicly available sites,
therefore you can hide your space
and access_token
by replacing them with ENV_
prepended variables.
This will look for the values in your system.
For example:
contentful:
spaces:
- example:
space: ENV_CONTENTFUL_SPACE_ID
access_token: ENV_CONTENTFUL_ACCESS_TOKEN
With this setup, your Space ID will be looked upon on ENV['CONTENTFUL_SPACE_ID']
and your Access Token
on ENV['CONTENTFUL_ACCESS_TOKEN']
. This way it is safe to share your code, without having to worry
about your credentials.
Jekyll itself only allows you to import code as plugins only for its recognized plugin entry points. Therefore we need to use a custom Rakefile to import the mapper and required files:
require 'jekyll'
require 'jekyll-contentful-data-import'
require './_plugins/mappers'
desc "Import Contentful Data with Custom Mappers"
task :contentful do
Jekyll::Commands::Contentful.process([], {}, Jekyll.configuration['contentful'])
end
Then proceed to run: bundle exec rake contentful
You can find working examples of multiple uses here.
Feel free to add your own examples by submitting a Pull Request. For more information, please check CONTRIBUTING.md