Feature: Merger of `_data`, additional file inclusion, and support for local themes

[vinorodrigues]

Firstly, thank you for your work on this plugin—it greatly enhances the flexibility of Jekyll sites by allowing the use of remote themes hosted on GitHub. I'd like to propose several enhancements that build upon the existing functionality, aiming to provide even greater flexibility and control to users.

Is feature request related to a problem?

No existing problem is related - but these feature have been discussed prior, either in issues or pull requests. These include:

• Issues:

  • 69

  • 81

  • 96

  • 100

• PR's

  • 89

Description of the solution requested

1. Merge Remote Theme _data with Local Site Data

As per #89

• Description:

  Enhance the plugin to load data from the remote theme's _data directory and merge it with the local site's data (site.data). The data from the theme would be loaded first, allowing the local site's data to override any matching keys. This ensures that default data provided by the theme can be customized or extended by the site.

• Use Case:

  • Themes can provide default configurations or content via _data files.
  • Site authors can override or extend this data without modifying the theme.
  • Example: The theme may provide a URL to a CDN public library, e.g. bootstrap.min.css, but site builders may want to override that URL. This is best managed in a data settings file of the theme that can be overriden.

• Benefits:

  • Promotes DRY (Don't Repeat Yourself) principles by centralising common data in the theme.
  • Simplifies site configuration when using themes that provide extensive data-driven features.

2. Optional Inclusion of Theme Files Based on _config.yml

As per #69 & #96

• Description:

  Introduce a new configuration option (remote_theme_include) in _config.yml that allows users to specify a list of files to include from the remote theme if they are not present in the local site. This is particularly useful for optional files like 404.html or custom assets.

• Use Case:

  • A theme provides a 404.html page that the site wants to use only if it doesn't have its own.
  • Including theme-provided assets or layouts only when they are not overridden locally.

• Benefits:

  • Increases flexibility in how themes are used and customised.
  • Avoids unnecessary duplication of files that are unchanged from the theme.
  • Allows for selective adoption of theme components.
  • Allows for swapping themes without necessitating re-edits of common files like the 404 file.

3. Support for Local Themes via local_theme Configuration

As per #96

• Description:

  Add the ability to source themes from a local directory specified by a new local_theme key in _config.yml. This would allow users to use themes stored within their project's directory structure (e.g., _themes/my_theme_1), in addition to remote themes. The remote_theme key retains precedence if both are specified.

  I'm aware that there is already a plugin for this, but incorporating this functionality to the benchmark plugin makes sense to me.

• Use Case:

  • Developing or customising a theme locally without publishing it to a GitHub repository.
  • Working in environments without internet access or where accessing external resources is restricted.

• Benefits:

  • Facilitates local theme development and testing.
  • Provides flexibility for users who prefer or require offline resources.
  • Enhances control over theme sourcing and versioning.
  • Allowing for quick theme swaps in a local or self-host environment.

Alternatives considered

• Data Merging:

  I've looked at PR #89, but am not confident that this addresses the merger of exiting data and that of site data. I have not experimented with that hypothesis, but the code just seems too brutal to work.

• File Inclusion:

  I've not seen this addressed in any code or poroposed code specifically to do with remote themes. Both issues #96 and #69 however ask for functionality that can be addressed with this wholly encapsulated request.

• Local Theme Support:

  I'm aware that ntkme/jekyll-local-theme exists... but wouldn't it be nice if this could do that too? :)

Additional context

Proposed Implementation Overview

Data Merging:

• Introduce a DataLoader class that reads data from the theme's _data directory.
• Merge theme data into site.data using Jekyll::Utils.deep_merge_hashes, with local data taking precedence.

File Inclusion:

• Add a FileIncluder class that checks for specified files in the local site.
• If a file is missing locally but exists in the theme, copy it into the site's source directory for inclusion.
• Clean up copied files after site render to ensure site author original files are unaffected.

Local Theme Support:

• Create a LocalTheme class that handles themes from a local directory.
• Modify the Munger class to initialize a LocalTheme instance when local_theme is specified.

[vinorodrigues]

PS:

I've started to try to resolve these myself, but I've literally needed to start learning how to code in Ruby, as that's not in my repertoire of languages I've worked on before.

If you'd like to see what I've come up with—and obviously I'd be keen to collaborate (with anyone) on this, or just [have you/them] take over—but keep in mind that I've not accounted for anything of an enterprise-level effort. No unit-testing, no comments—just code churn and hope it works.

Anyway, it's here:

• unvino/fork.benbalter.jekyll-remote-theme, branch vr-propagate-files

• Diff here

---

• [x] Mostly the functionality is not reading the files from the unzipped theme, and I can't figure it out... yet. [0a72db2]
• [x] Still need to test the data merger [c4ecfab]
• [x] Still need to test local theme function
• [x] -- Also had a stab at issue #81 [342bd72]

---

:bangbang: I've done some of my own use testing and all seams good and working. Would love to see it tried out in the wild ...

I'll hold off on any PR-ing until I get a sanity check on this, and a confirmation that it's working. TY to those willing ;)