{"id":13612448,"url":"https://github.com/contentful/jekyll-contentful-data-import","last_synced_at":"2025-09-29T12:30:43.894Z","repository":{"id":3097758,"uuid":"48241026","full_name":"contentful/jekyll-contentful-data-import","owner":"contentful","description":"Contentful Plugin for the Jekyll Static Site Generator","archived":true,"fork":false,"pushed_at":"2023-10-26T13:44:48.000Z","size":101,"stargazers_count":101,"open_issues_count":9,"forks_count":32,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-09-27T10:02:24.354Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/contentful.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-12-18T15:01:37.000Z","updated_at":"2024-08-31T20:21:14.000Z","dependencies_parsed_at":"2024-01-14T05:09:22.414Z","dependency_job_id":null,"html_url":"https://github.com/contentful/jekyll-contentful-data-import","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentful%2Fjekyll-contentful-data-import","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentful%2Fjekyll-contentful-data-import/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentful%2Fjekyll-contentful-data-import/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contentful%2Fjekyll-contentful-data-import/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/contentful","download_url":"https://codeload.github.com/contentful/jekyll-contentful-data-import/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234619407,"owners_count":18861457,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T20:00:30.023Z","updated_at":"2025-09-29T12:30:38.602Z","avatar_url":"https://github.com/contentful.png","language":"Ruby","funding_links":[],"categories":["Other","HarmonyOS","Ruby"],"sub_categories":["Windows Manager"],"readme":"# Jekyll-Contentful-Data-Import\n\n[![Build Status](https://travis-ci.org/contentful/jekyll-contentful-data-import.svg?branch=master)](https://travis-ci.org/contentful/jekyll-contentful-data-import)\n\n[Contentful](https://www.contentful.com) provides a content infrastructure for digital teams to power content in websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship digital products faster.\n\nJekyll-Contentful-Data-Import is a [Jekyll](http://jekyllrb.com/) extension to use the Jekyll static site generator together with [Contentful](https://www.contentful.com). It is powered by the [Contentful Ruby Gem](https://github.com/contentful/contentful.rb).\n\nExperience the power of Jekyll while staying sane as a developer by letting end-users edit content in a web-based interface.\n\n## Installation\n\nCreate a Gemfile in your Jekyll project and add the following:\n\n```ruby\nsource 'https://rubygems.org'\n\ngroup :jekyll_plugins do\n  gem \"jekyll-contentful-data-import\"\nend\n```\n\nThen as usual, run:\n\n```bash\nbundle install\n```\n\n## Usage\n\nRun `jekyll contentful` in your terminal. This will fetch entries for the configured\nspaces and content types and put the resulting data in the\n[local data folder](http://jekyllrb.com/docs/datafiles/) as yaml files.\n\n### --rebuild option\n\nThe `contentful` command has a `--rebuild` option which will trigger a rebuild of your site\n\n## Configuration\n\nTo configure the extension, add the following configuration block to Jekyll's `_config.yml`:\n\n```yaml\ncontentful:\n  spaces:\n    - example:                              # Jekyll _data folder identifier - Required\n        space: cfexampleapi                 # Required\n        access_token: b4c0n73n7fu1          # Required\n        environment: master                 # Optional\n        cda_query:                          # Optional\n          include: 2\n          limit: 100\n        all_entries: true                   # Optional - Defaults to false, only grabbing the amount set on CDA Query\n        all_entries_page_size: 1000         # Optional - Defaults to 1000, maximum amount of entries per CDA Request for all_entries\n        content_types:                      # Optional\n          cat: MyCoolMapper\n        client_options:                     # Optional\n          api_url: 'preview.contentful.com' # Defaults to 'api.contentful.com' which is Production\n          max_include_resolution_depth: 5   # Optional - Defaults to 20, maximum amount of levels to resolve includes\n        base_path: app_path                 # Optional - Defaults to Current directory\n        destination: destination_in_data    # Optional - Defaults to _data/contentful/spaces\n        individual_entry_files: true        # Optional - Defaults to false\n        rich_text_mappings:                 # Optional - Defaults to {}\n          embedded-entry-block: MyEntryRenderer\n```\n\nParameter              | Description\n----------             | ------------\nspace                  | Contentful Space ID\naccess_token           | Contentful Delivery API access token\nenvironment            | Space environment, defaults to `master`\ncda_query              | Hash describing query configuration. See [contentful.rb](https://github.com/contentful/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.\nall_entries            | Boolean, if true will run multiple queries to the API until it fetches all entries for the space\nall_entries_page_size  | Integer, the amount of maximum entries per CDA Request when fetching :all_entries\ncontent_types          | Hash describing the mapping applied to entries of the imported content types\nclient_options         | Hash describing `Contentful::Client` configuration. See [contentful.rb](https://github.com/contentful/contentful.rb) for more info.\nbase_path              | String with path to your Jekyll Application, defaults to current directory. Path is relative to your current location.\ndestination            | String with path within `_data` under which to store the output yaml file. Defaults to contentful/spaces\nindividual_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.\nrich_text_mappings     | Hash with `'nodeTyoe' =\u003e RendererClass` pairs determining overrides for the [`RichTextRenderer` library](https://github.com/contentful/rich-text-renderer.rb) configuration.\n\nYou can add multiple spaces to your configuration\n\n## Entry mapping\n\nThe extension will transform every fetched entry before storing it as a yaml file in the local\ndata folder. If a custom mapper is not specified a default one will be used.\n\nThe default mapper will map fields, assets and linked entries.\n\n### Custom Mappers\n\nYou can create your own mappers if you need to. The only requirement for a class to behave as a\nmapper is to have a `map` instance method.\n\nFollowing is an example of such custom mapper that reverses all entry field IDs:\n\n```ruby\nclass MyReverseMapper \u003c ::Jekyll::Contentful::Mappers::Base\n  def map\n    result = super\n    reversed_result = {}\n\n    result.each do |k, v|\n      reversed_result[k.reverse] = v\n    end\n\n    reversed_result\n  end\nend\n```\n\n#### Caveats\n\n**Note:** This has changed since previous version.\n\nWhen creating custom mappers, you should create them in a file under `#{source_dir}/_plugins/mappers/`.\nThis will allow the autoload mechanism that has been included in the latest version.\n\nWith the autoload mechanism, there is no longer a need to create a `rake` task for importing using custom mappers.\n\nIf you already have a custom `rake` task, the new autoload mechanism will not affect it from working as it was working previously.\n\n### Rich Text *Beta*\n\nTo render rich text in your views, you can use the `rich_text` filter:\n\n```liquid\n{{ entry.rich_text_field | rich_text }}\n```\n\nThis will output the generated HTML generated by the [`RichTextRenderer` library](https://github.com/contentful/rich-text-renderer.rb).\n\n#### Adding custom renderers\n\nWhen using rich text, if you're planning to embed entries, then you need to create your custom renderer for them. You can read how create your own renderer classes [here](https://github.com/contentful/rich-text-renderer.rb#using-different-renderers).\n\nTo configure the mappings, you need to add them in your `contentful` block like follows:\n\n```yaml\ncontentful:\n  spaces:\n    - example:\n      # ... all the regular config ...\n      rich_text_mappings:\n        embedded-entry-block: MyCustomRenderer\n```\n\nYou can also add renderers for all other types of nodes if you want to have more granular control over the rendering.\n\nThis will use the same autoload strategy included for custom entry mappers, therefore, you should include your mapper classes in `#{source_dir}/_plugins/mappers/`.\n\n#### Using the helper with multiple Contentful spaces\n\nIn case you have multiple configured spaces, and have different mapping configurations for them. You can specify which space you want to pull the configuration from when using the helper.\n\nThe helper receives an additional optional parameter for the space name. By default it is `nil`, indicating the first available space.\n\nSo, if for example you have 2 spaces with different configurations, to use the space called `foo`, you should call the helper as: `{{ entry.field | rich_text: \"foo\" }}`.\n\n### Hiding Space and Access Token in Public Repositories\n\nIn most cases you may want to avoid including your credentials in publicly available sites,\ntherefore you can do the following:\n\n1. `bundle update` — make sure your gem version supports `ENV_` variables\n\n2. Set up your `_config` like so:\n\n  ```yaml\n  contentful:\n    spaces:\n      - example:\n          space:        ENV_CONTENTFUL_SPACE_ID\n          access_token: ENV_CONTENTFUL_ACCESS_TOKEN\n          environment:  ENV_CONTENTFUL_ENVIRONMENT\n  ```\n\n  (Your Space ID will be looked upon on `ENV['CONTENTFUL_SPACE_ID']`, your Access Token on `ENV['CONTENTFUL_ACCESS_TOKEN']` and your environment on `ENV['CONTENTFUL_ENVIRONMENT']`.)\n\n3. Either add the following variables to your shell's configuration file (.bashrc or .bash_profile, for example):\n\n  ```bash\n  export CONTENTFUL_ACCESS_TOKEN=abc123\n  export CONTENTFUL_SPACE_ID=abc123\n  export CONTENTFUL_ENVIRONMENT=master\n  ```\n\n  (And run `source ~/.bashrc` or open new terminal to enable changes.)\n\n  Or specify them on the command line:\n\n  ```bash\n  CONTENTFUL_ACCESS_TOKEN=abc123 CONTENTFUL_SPACE_ID=abc123 CONTENTFUL_ENVIRONMENT=master jekyll contentful\n  ```\n\n4. Party.\n\nThis way, it is safe to share your code without having to worry\nabout your credentials.\n\n### Using Multiple Entry Files\n\nWhen setting the `individual_entry_files` flag to true, the usage pattern changes a little,\nas Jekyll does not allow for variable unpacking when iterating.\n\nA usage example is as follows:\n\n```html\n\u003cul class=\"cat-list\"\u003e\n  \u003c!-- Each element in the array of entries for a content type is an array of the form ['entry_id', { ... entry_data ...}] --\u003e\n  {% for cat_data in site.data.contentful.spaces.example.cat %}\n    {% assign cat_id = cat_data[0] %} \u003c!-- Entry ID is the first element of the array --\u003e\n    {% assign cat = cat_data[1] %} \u003c!-- Entry data is the second element of the array --\u003e\n    \u003cli\u003e\n      \u003cp\u003e{{ cat_id }}: {{ cat.name }}\u003c/p\u003e\n    \u003c/li\u003e\n  {% endfor %}\n\u003c/ul\u003e\n```\n\n## Examples\n\nYou can find working examples of multiple uses [here](https://github.com/contentful/contentful_jekyll_examples).\n\n## Contributing\n\nFeel free to add your own examples by submitting a Pull Request. For more information,\nplease check [CONTRIBUTING.md](./CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontentful%2Fjekyll-contentful-data-import","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontentful%2Fjekyll-contentful-data-import","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontentful%2Fjekyll-contentful-data-import/lists"}