class GitHubPages::Configuration
Sets and manages Jekyll configuration defaults and overrides
Constants
- CONFIGS_WITH_METHODS
These configuration settings have corresponding instance variables on Jekyll::Site and need to be set properly when the config is updated.
- DEFAULTS
Default, user overwritable options
- DEFAULT_PLUGINS
Backward compatability of constants
- DEVELOPMENT_PLUGINS
- OVERRIDES
Options which GitHub Pages sets, regardless of the user-specified value
The following values are also overridden by GitHub Pages, but are not overridden locally, for practical purposes:
-
source
-
destination
-
jailed
-
verbose
-
incremental
-
GH_ENV
-
- PLUGIN_WHITELIST
- PRODUCTION_DEFAULTS
User-overwritable defaults used only in production for practical reasons
- THEMES
Public Class Methods
# File lib/github-pages/configuration.rb, line 89 def defaults_for_env defaults = development? ? DEFAULTS : PRODUCTION_DEFAULTS Jekyll::Utils.deep_merge_hashes Jekyll::Configuration::DEFAULTS, defaults end
# File lib/github-pages/configuration.rb, line 85 def development? Jekyll.env == "development" end
# File lib/github-pages/configuration.rb, line 81 def disable_whitelist? development? && !ENV["DISABLE_WHITELIST"].to_s.empty? end
Given a user's config, determines the effective configuration by building a user configuration sandwhich with our overrides overriding the user's specified values which themselves override our defaults.
Returns the effective Configuration
Note: this is a highly modified version of Jekyll#configuration
# File lib/github-pages/configuration.rb, line 101 def effective_config(user_config) # Merge user config into defaults config = Jekyll::Utils.deep_merge_hashes(defaults_for_env, user_config) .fix_common_issues .add_default_collections # Allow theme to be explicitly disabled via "theme: null" config["theme"] = user_config["theme"] if user_config.key?("theme") migrate_theme_to_remote_theme(config) exclude_cname(config) # Merge overwrites into user config config = Jekyll::Utils.deep_merge_hashes config, OVERRIDES restrict_and_config_markdown_processor(config) configure_plugins(config) config end
# File lib/github-pages/configuration.rb, line 77 def processed(site) site.instance_variable_set :@_github_pages_processed, true end
# File lib/github-pages/configuration.rb, line 73 def processed?(site) site.instance_variable_get(:@_github_pages_processed) == true end
Set the site's configuration. Implemented as an `after_reset` hook. Equivalent set! function contains the code of interest. This function guards against double-processing via the value in processed.
# File lib/github-pages/configuration.rb, line 126 def set(site) return if processed? site debug_print_versions set!(site) processed(site) end
Set the site's configuration with all the proper defaults and overrides. Should be called by set to protect against multiple processings.
# File lib/github-pages/configuration.rb, line 136 def set!(site) site.config = effective_config(site.config) end
Private Class Methods
Requires default plugins and configures whitelist in development
# File lib/github-pages/configuration.rb, line 173 def configure_plugins(config) # Ensure we have those gems we want. config["plugins"] = Array(config["plugins"]) | DEFAULT_PLUGINS # To minimize errors, lazy-require jekyll-remote-theme if requested by the user config["plugins"].push("jekyll-remote-theme") if config.key? "remote_theme" return unless development? if disable_whitelist? config["whitelist"] = config["whitelist"] | config["plugins"] end config["whitelist"] = config["whitelist"] | DEVELOPMENT_PLUGINS end
Print the versions for github-pages and jekyll to the debug stream for debugging purposes. See by running Jekyll with '–verbose'
# File lib/github-pages/configuration.rb, line 191 def debug_print_versions Jekyll.logger.debug "GitHub Pages:", "github-pages v#{GitHubPages::VERSION}" Jekyll.logger.debug "GitHub Pages:", "jekyll v#{Jekyll::VERSION}" end
If the user's 'exclude' config is the default, also exclude the CNAME
# File lib/github-pages/configuration.rb, line 166 def exclude_cname(config) return unless config["exclude"].eql? Jekyll::Configuration::DEFAULTS["exclude"] config["exclude"].concat(DEFAULTS["exclude"]) end
If the user has set a 'theme', then see if we can automatically use remote theme instead.
# File lib/github-pages/configuration.rb, line 161 def migrate_theme_to_remote_theme(config) # This functionality has been rolled back due to complications with jekyll-remote-theme. end
Ensure we're using Kramdown or GFM. Force to Kramdown if neither of these.
This can get called multiply on the same config, so try to be idempotentish.
# File lib/github-pages/configuration.rb, line 147 def restrict_and_config_markdown_processor(config) config["markdown"] = "kramdown" unless \ %w(kramdown gfm commonmarkghpages).include?(config["markdown"].to_s.downcase) return unless config["markdown"].to_s.casecmp("gfm").zero? config["markdown"] = "CommonMarkGhPages" config["commonmark"] = { "extensions" => %w(table strikethrough autolink tagfilter), "options" => %w(footnotes), } end