Coder Social home page Coder Social logo

felixjung / jekyll-contentful-data-import Goto Github PK

View Code? Open in Web Editor NEW

This project forked from contentful/jekyll-contentful-data-import

0.0 1.0 1.0 72 KB

Contentful Plugin for the Jekyll Static Site Generator

License: MIT License

Ruby 100.00%

jekyll-contentful-data-import's Introduction

Jekyll-Contentful-Data-Import

Build Status

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.

Installation

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

Usage

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.

--rebuild option

The contentful command has a --rebuild option which will trigger a rebuild of your site

Configuration

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
        destination: destination_in_data # Optional - Defaults to _data/contentful/spaces
        individual_entry_files: true # Optional - Defaults to false
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.
destination String with path within _data under which to store the output yaml file. Defaults to contentful/spaces
individual_entry_files Boolean, if true will create an individual file per entry separated in folders by content type, file path will be {space_alias}/{content_type_id}/{entry_id}.yaml. Default behavior is to create a file per space. Usage is affected when this is set to true, please look in the section below.

You can add multiple spaces to your configuration

Entry mapping

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.

Custom Mappers

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 reverses all entry field IDs:

class MyReverseMapper < ::Jekyll::Contentful::Mappers::Base
  def map
    result = super
    reversed_result = {}

    result.each do |k, v|
      reversed_result[k.reverse] = v
    end

    reversed_result
  end
end

Caveats

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

Hiding Space and Access Token in Public Repositories

In most cases you may want to avoid including your credentials in publicly available sites, therefore you can do the following:

  1. bundle update โ€” make sure your gem version supports ENV_ variables

  2. Set up your _config like so:

contentful:
  spaces:
    - example:
        space:        ENV_CONTENTFUL_SPACE_ID
        access_token: ENV_CONTENTFUL_ACCESS_TOKEN

(Your Space ID will be looked upon on ENV['CONTENTFUL_SPACE_ID'] and your Access Token on ENV['CONTENTFUL_ACCESS_TOKEN'].)

  1. Either add the following variables to your shell's configuration file (.bashrc or .bash_profile, for example):
export CONTENTFUL_ACCESS_TOKEN=abc123
export CONTENTFUL_SPACE_ID=abc123

(And run source ~/.bashrc or open new terminal to enable changes.)

Or specify them on the command line:

CONTENTFUL_ACCESS_TOKEN=abc123 CONTENTFUL_SPACE_ID=abc123 jekyll contentful
  1. Party.

This way, it is safe to share your code without having to worry about your credentials.

Using Multiple Entry Files

When setting the individual_entry_files flag to true, the usage pattern changes a little, as Jekyll does not allow for variable unpacking when iterating.

A usage example is as follows:

<ul class="cat-list">
  <!-- Each element in the array of entries for a content type is an array of the form ['entry_id', { ... entry_data ...}] -->
  {% for cat_data in site.data.contentful.spaces.example.cat %}
    {% assign cat_id = cat_data[0] %} <!-- Entry ID is the first element of the array -->
    {% assign cat = cat_data[1] %} <!-- Entry data is the second element of the array -->
    <li>
      <p>{{ cat_id }}: {{ cat.name }}</p>
    </li>
  {% endfor %}
</ul>

Examples

You can find working examples of multiple uses here.

Contributing

Feel free to add your own examples by submitting a Pull Request. For more information, please check CONTRIBUTING.md

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.