github/jekyll
1
1
Fork 0
mirror of https://github.com/jekyll/jekyll.git synced 2026-04-28 03:01:03 -04:00
Code Issues Packages Projects Releases Wiki Activity

Load config file from within current theme-gem (#7304)

Browse Source 
Merge pull request 7304
This commit is contained in:
Ashwin Maroli
2018-10-28 15:38:32 +05:30
committed by jekyllbot
parent 56c35f1a7d
commit d67cbb4e5f
5 changed files with 83 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/_docs/themes.md
View File

@@ -274,6 +274,24 @@ Jekyll will automatically require all whitelisted `runtime_dependencies` of your
With this, the end-user need not keep track of the plugins required to be included in their config file for their theme-gem to work as intended.
{% if site.version == '4.0.0' %}
{% comment %} Remove this encapsulation when `v4.0` ships {% endcomment %}
### Pre-configuring Theme-gems {%- include docs_version_badge.html version="4.0.0" -%}
Jekyll will read-in a `_config.yml` at the root of the theme-gem and merge its data into the site's existing configuration data.
But unlike other entities loaded from within the theme, loading the config file comes with a few restrictions, as summarized below:
* Jekyll's default settings cannot be overridden by a theme-config. That *ball is still in the user's court.*
* The theme-config-file cannot be a symlink, irrespective of `safe mode` and whether the file pointed to by the symlink is a legitimate file within the theme-gem.
* The theme-config should be a set of key-value pairs. An empty config file, a config file that simply *lists items* under a key, or a config file with just a simple string of text will simply be ignored silently. Users will not get a warning or any log output regarding this discrepancy.
* Any settings defined by the theme-config can be overridden by the user.
While this feature is to enable easier adoption of a theme, the restrictions ensure that a theme-config cannot affect the build in a concerning manner. Any plugins required by the theme will have to be listed manually by the user or provided by the theme's `gemspec` file.
This feature will let the theme-gem to work with *theme-specific config variables* out-of-the-box.
{% endif %}
### Documenting your theme
Your theme should include a `/README.md` file, which explains how site authors can install and use your theme. What layouts are included? What includes? Do they need to add anything special to their site's configuration file?