class GitHubPages::Configuration

Sets and manages Jekyll configuration defaults and overrides

Constants

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

defaults_for_env() click to toggle source
# File lib/github-pages/configuration.rb, line 82
def defaults_for_env
  defaults = development? ? DEFAULTS : PRODUCTION_DEFAULTS
  Jekyll::Utils.deep_merge_hashes Jekyll::Configuration::DEFAULTS, defaults
end
development?() click to toggle source
# File lib/github-pages/configuration.rb, line 78
def development?
  Jekyll.env == "development"
end
disable_whitelist?() click to toggle source
# File lib/github-pages/configuration.rb, line 74
def disable_whitelist?
  development? && !ENV["DISABLE_WHITELIST"].to_s.empty?
end
effective_config(user_config) click to toggle source

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 94
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
processed(site) click to toggle source
# File lib/github-pages/configuration.rb, line 70
def processed(site)
  site.instance_variable_set :@_github_pages_processed, true
end
processed?(site) click to toggle source
# File lib/github-pages/configuration.rb, line 66
def processed?(site)
  site.instance_variable_get(:@_github_pages_processed) == true
end
set(site) click to toggle source

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 119
def set(site)
  return if processed? site

  debug_print_versions
  set!(site)
  processed(site)
end
set!(site) click to toggle source

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 129
def set!(site)
  site.config = effective_config(site.config)
end

Private Class Methods

configure_plugins(config) click to toggle source

Requires default plugins and configures whitelist in development

# File lib/github-pages/configuration.rb, line 166
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
debug_print_versions() click to toggle source

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 184
def debug_print_versions
  Jekyll.logger.debug "GitHub Pages:", "github-pages v#{GitHubPages::VERSION}"
  Jekyll.logger.debug "GitHub Pages:", "jekyll v#{Jekyll::VERSION}"
end
exclude_cname(config) click to toggle source

If the user’s ‘exclude’ config is the default, also exclude the CNAME

# File lib/github-pages/configuration.rb, line 159
def exclude_cname(config)
  return unless config["exclude"].eql? Jekyll::Configuration::DEFAULTS["exclude"]

  config["exclude"].concat(DEFAULTS["exclude"])
end
migrate_theme_to_remote_theme(config) click to toggle source

If the user has set a ‘theme’, then see if we can automatically use remote theme instead.

# File lib/github-pages/configuration.rb, line 154
def migrate_theme_to_remote_theme(config)
  # This functionality has been rolled back due to complications with jekyll-remote-theme.
end
restrict_and_config_markdown_processor(config) click to toggle source

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 140
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(unsafe footnotes),
  }
end