{"id":13612051,"url":"https://github.com/ashmaroli/jekyll-data","last_synced_at":"2025-10-30T13:47:24.952Z","repository":{"id":55010792,"uuid":"71054423","full_name":"ashmaroli/jekyll-data","owner":"ashmaroli","description":"A plugin to read '_config.yml' and data files within Jekyll theme gems","archived":false,"fork":false,"pushed_at":"2021-01-24T06:22:14.000Z","size":103,"stargazers_count":46,"open_issues_count":1,"forks_count":11,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-08-30T15:52:03.963Z","etag":null,"topics":["jekyll","jekyll-plugin","reader","ruby"],"latest_commit_sha":null,"homepage":"","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/ashmaroli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-16T14:10:03.000Z","updated_at":"2025-08-07T02:45:19.000Z","dependencies_parsed_at":"2022-08-14T09:00:49.482Z","dependency_job_id":null,"html_url":"https://github.com/ashmaroli/jekyll-data","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/ashmaroli/jekyll-data","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmaroli%2Fjekyll-data","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmaroli%2Fjekyll-data/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmaroli%2Fjekyll-data/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmaroli%2Fjekyll-data/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashmaroli","download_url":"https://codeload.github.com/ashmaroli/jekyll-data/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmaroli%2Fjekyll-data/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274645785,"owners_count":25323977,"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","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["jekyll","jekyll-plugin","reader","ruby"],"created_at":"2024-08-01T20:00:21.687Z","updated_at":"2025-10-30T13:47:19.920Z","avatar_url":"https://github.com/ashmaroli.png","language":"Ruby","readme":"# JekyllData\n\n[![Gem Version](https://img.shields.io/gem/v/jekyll-data.svg)](https://rubygems.org/gems/jekyll-data)\n[![Build Status](https://img.shields.io/travis/ashmaroli/jekyll-data/master.svg?label=Build%20Status)][travis]\n\n[travis]: https://travis-ci.org/ashmaroli/jekyll-data\n\nIntroducing a plugin that reads data files within **jekyll theme-gems** and adds the resulting hash to the site's internal data hash. If a **`_config.yml`** is present at the root of the theme-gem, it will be evaluated and the extracted hash data will be incorporated into the site's existing config hash.\n\n\n## Installation\n\nSimply add the plugin to your site's Gemfile and config file like every other jekyll plugin gem:\n\n```ruby\n# Gemfile\n\ngroup :jekyll_plugins do\n  gem \"jekyll-data\"\nend\n```\n..and run\n\n    bundle install\n\n\n\u003e **Note: If the plugin has been marked as a `runtime_dependency` by the theme-gem's author it will be installed automatically with the theme-gem. Yet, it is recommended that the plugin be added to `:jekyll_plugins` group in the Gemfile rather than the `gems:` array in the config file while building or serving the site to avoid 'overriding' the `gems:` array data that may have been read-in from the theme-gem.**\n\n\n## Usage\n\nAs long as the plugin-gem has been installed properly, and is included in the Gemfile's `:jekyll_plugins` group, data files supported by Jekyll and present in the `_data` directory at the root of your theme-gem will be read. Their contents will be added to the site's internal data hash, provided, an identical data hash doesn't already exist at the site-source.\n\nIf the theme-gem also includes a `_config.yml` at its root, then it will be read as well. The resulting config hash will be mixed into the site's existing config hash, filling in where the *keys* are not already defined. In other words, the config file at `source` will override corresponding identical keys in a `_config.yml` within the theme-gem which would in turn override corresponding `DEFAULTS` from Jekyll:\n\n  **DEFAULTS** \u003c **_config.yml in theme-gem** \u003c **_config.yml at source** \u003c **Override configs via command-line**.\n\n\n### Theme Configuration\n\nJekyll themes (built prior to `Jekyll 3.2`) usually ship with configuration settings defined in the config file, which are then used within the theme's template files directly under the `site` namespace (e.g. `{{ site.myvariable }}`). This is not possible with theme-gems as a config file and data files within gems are not natively read (as of Jekyll 3.3), and hence require end-users to inspect a *demo* or *example* directory to source those files.\n\nThis plugin provides a solution to that hurdle:\n\nJekyllData now reads the config file (at present only `_config.yml`) present within the theme-gem and uses the data to modify the site's config hash. This allows the theme-gem to continue using `{{ site.myvariable }}` within its templates and work out-of-the-box as intended, with minimal user intervention.\n\n**Note: the plugins required by the theme may be listed under the `gems:` array and will be automatically `required` by Jekyll while building/serving, provided that the user doesn't have a different `gems:` array in the config file at source. Hence it is recommended to add all other plugins ( including `jekyll-data` ) via the Gemfile's `:jekyll_plugins` group.**\n\n#### The `theme` namespace\n\nFrom `v1.0`, JekyllData no longer supports reading theme configuration provided as a `[theme-name].***` file within the `_data` directory and instead the `theme` namespace points to a certain key in the bundled `_config.yml`.\n\nFor `{{ theme.variable }}` to work, the config file should nest all such key-value pairs under the `[theme-name]` key, as outlined in the example below for a theme-gem called `solitude`:\n\n```yaml\n# \u003csolitude-0.1.0\u003e/_config.yml\n\n# the settings below have been used in this theme's templates via the `theme`\n# namespace. e.g. `{{ theme.recent_posts.style }}` instead of using the more\n# verbose `{{ site.solitude.recent_posts.style }}` though both are functionally\n# the same.\n#\nsolitude:\n  sidebar       : true      # enter 'false' to enable horizontal navbar instead.\n  theme_variant : Charcoal  # choose from 'Ocean', 'Grass', 'Charcoal'\n  recent_posts  :\n    style       : list      # choose from 'list' and 'grid'.\n    quantity    : '4'       # either '4' or '6'\n\n```\n\n\n### Data files\n\nData files may be used to supplement theme templates (e.g. locales and translated UI text) and can be named as desired.\n  - Organize related small data files in sub-directories. (or)\n  - Declare all related data as mapped data blocks within a single file.\n\nTo illustrate with an example, consider a `locales.yml` that has mappings for `en:`, `fr:`, `it:`.\n\n```yaml\n# \u003ctheme-gem\u003e/_data/locales.yml\n\nen:\n  previous : previous\n  next     : next\n\nfr:\n  previous : précédent\n  next     : prochain\n\nit:\n  previous : precedente\n  next     : successivo\n```\n\nthe Hash from above would be identical to one had the gem been shipped with a `_data/locales` directory containing individual files for each language data.\n\n\n### Overriding Data Files\n\nTo override data shipped with a theme-gem, simply have an identical hash at the site-source.\n\nIrrespective of whether the theme-gem ships with consolidated data files of related entities, or sub-directories containing individual files, the data can be overridden with a single file or with multiple files.\n\nFor example, if a theme-gem contains the above sample `locales.yml`, then to override the `fr:` key-data simply have either of the following:\n  - a **`_data/locales/fr.yml`** with identical subkey(s).\n  - a **`_data/locales.yml`** with **`fr:`** with identical subkey(s).\n\n--\n\u003e **Note**\n  - having an **empty** `_data/locales.yml` at `source` directory will override the **entire `[\"data\"][\"locales\"]` payload** from the theme-gem as **`false`**.\n  - having an **empty** `_data/locales/fr.yml` at `source` directory will override the **enire `[\"data\"][\"locales\"][\"fr\"]` payload** from the theme-gem as **`false`**\n\n\n## Contributing\n\nBug reports and pull requests are welcome at the [GitHub Repo](https://github.com/ashmaroli/jekyll-data). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","funding_links":[],"categories":["Settings \u0026 Configurations Tweaks","Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashmaroli%2Fjekyll-data","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashmaroli%2Fjekyll-data","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashmaroli%2Fjekyll-data/lists"}