jekyll-scry-content

Jekyll plugin that discovers Scry content gems (scry-*), stages their content/ files into the site source as symlinks, and merges optional config files referenced from each gem's manifest.

group :jekyll_plugins do
  gem "jekyll-scry-content", "~> 0.3"
  # Content gems can live in this group or outside it; discovery does not care.
  gem "scry-rpg-callouts", "~> 1.0"
end

gem "scry-seers-sanctum", "~> 3.2"

# _config.yml
plugins:
  - jekyll-scry-content

scry_content:
  enabled: true
  only: []
  exclude: []
  warn_missing_ruleset: true   # default true
  warn_missing_content: true   # default true

Pin gemspec versions in the Gemfile (~> 3.2). Manifest version is the product/edition string and may differ; the loader logs both.

scry-example/
├── lib/
│   └── scry-example.rb       # no-op; so `require` works in :jekyll_plugins
├── content/
│   ├── manifest.yml          # schema_version: 1
│   ├── docs/…
│   └── assets/…
└── *.gemspec                 # metadata["scry_content"] = "true"
                              # add_dependency "jekyll-scry-content", "~> 0.3"

The lib/ file must be named after the gem and should not require this plugin or call register. Discovery uses gemspec metadata.

Content gems should add_dependency "jekyll-scry-content", "~> 0.3" now that this plugin is on RubyGems. Keep the loader in the host :jekyll_plugins group (and plugins: in _config.yml) so its hooks actually run — a transitive install alone does not register them.

Site-owned files always win over gem symlinks. Staged paths are listed in .gitignore between # BEGIN jekyll-scry-content markers.

Supported: 1. Missing schema_version warns and is treated as 1. An unsupported value fails the build. Excluded gems are not validated.

A content gem can merge keys into the host site's config by pointing the manifest at a YAML file under content/. That file is loaded in memory only — it is not staged into the site source, and it must not be named _config.yml (Jekyll would treat that as site config).

# content/manifest.yml
kind: style
config_file: config.yml

# content/config.yml
callouts:
  monster:
    title: Monster
    color: red

Later gems overlay earlier gems; values in the site _config.yml win on conflicts. This is how scry-rpg-callouts registers Just the Docs callouts.

A content gem can declare other content it needs:

requires:
  rulesets: [ose]            # ids from ruleset gems (`provides` / ruleset `id`)
  content: [rpg-callouts]    # content-gem id or gem name

Missing requirements warn by default (warn_missing_ruleset and warn_missing_content are true if omitted). Set either flag to false to silence that check. missing_ruleset: error still fails the build; missing_ruleset: ignore still disables ruleset warnings when warn_missing_ruleset is omitted.

Rulesets should stay host Gemfile lines, not gemspec runtime dependencies, so a site can omit them.

Plugins such as jekyll-image-links read map YAML from site.source at build time. Staging keeps those paths identical to in-repo adventures without vendoring files in the site repository.